Metadata-Version: 2.4
Name: stanley_cbp
Version: 0.1.69
Summary: Algorithm developed to conduct a systematic search for exoplanets orbiting eclipsing binary stars.
Author-email: David Martin <David.Martin@tufts.edu>, "Chanita (Wata) Tubthong" <Chanita.Tubthong@tufts.edu>, Tess Kleanthous <Tess.Kleanthous@tufts.edu>
License: MIT License
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: License.txt
Requires-Dist: numpy>=1.22
Requires-Dist: scipy>=1.10
Requires-Dist: pandas>=1.5
Requires-Dist: matplotlib>=3.7
Requires-Dist: astropy>=5.0
Requires-Dist: astroquery>=0.4
Requires-Dist: lightkurve>=2.4
Requires-Dist: batman-package>=2.4
Requires-Dist: rebound>=4.4
Requires-Dist: wotan<2.0,>=1.10
Requires-Dist: PyAstronomy>=0.18
Requires-Dist: ldtk>=1.3
Requires-Dist: ipython>=8.0
Dynamic: license-file

# Stanley Pipeline

**Stanley** is a research pipeline for detecting, modeling, and analyzing **eclipsing binaries** and potential **circumbinary planets (CBPs)** in space-based photometric data. It was originally developed for the **Kepler** CBP sample and has since been extended to large-scale searches in **TESS** light curves. In circumbinary systems, planetary transits do **not** occur at regular intervals and transit durations vary significantly due to the orbital motion of both stars around the barycenter. As a result, conventional single-star transit search algorithms perform poorly. **Stanley** implements methods specifically optimized for the **variable-timing and variable-duration** transit signatures unique to circumbinary planets.

## Core Capabilities
### Detrending
- Iterative cosine (COFIAM-like) filtering
- TESS-specific quadratic baseline removal
- Variable-duration biweight filters
- Outlier / flare / kink removal
- Optional ellipsoidal and reflection trend modeling

### Binary Modeling & Validation
- Robust eclipse identification
- Multi-stage BLS period and harmonic validation
- Extraction of binary parameters (P, e, omega, eclipse depths and widths)

### Secondary Eclipse Vetting
- Geometric feasibility tests
- Inclination / eccentricity constraints

### Transit Timing Variation Search
- N-body forward modeling via **REBOUND**
- Variable-duration transit stacking matched to dynamically predicted timing signatures

### Scalable Execution
- Fully HPC-compatible (SLURM)
- Each module (detrending, search, analysis) may run independently or as a unified pipeline
- Interpolative potential for less computational load

## Scientific Context
Stanley was first validated on the **Kepler** circumbinary-planet sample, where it successfully recovered all known CBPs including **Kepler-47 b/c/d**, searched for additional planets using variable-duration stacked transit detection, and demonstrated sensitivity to planets smaller than roughly three Earth radii in about half the systems. The current version extends the pipeline to **TESS**, enabling large-scale searches of low-mass eclipsing binaries and supporting **demographic studies** of small circumbinary planets.

## Repository Structure and Data Requirements

This repository contains only the core **source code** (`stanley_cbp/`). All static catalogs needed at runtime are packaged inside:

    stanley_cbp/Databases/

For standard local or Jupyter-based usage, users do not need to download any external data or set any environment variables.

Instead, when running the pipeline (typically from the `Tutorials/` folder), Stanley automatically creates and manages a local runtime workspace containing:

- LightCurves/
- PlanetSearchOutput/
- UserGeneratedData/

This workspace is created relative to the working directory and requires no manual configuration.

## Runtime workspace (HPC / cluster use)
For large-scale or cluster-based runs, users may optionally define a runtime workspace via an environment variable:

`export STANLEY_RUN_ROOT="/path/to/your/STANLEY/Runs"`

When `STANLEY_RUN_ROOT` is set, all runtime products (light curves, diagnostics, and search outputs) are written under this directory instead of the local working directory. This is recommended for HPC environments where scratch space, quotas, or shared filesystems are involved.

If `STANLEY_RUN_ROOT` is not set, STANLEY falls back to the default local behavior described above.

## Installation
Install from PyPI: pip install stanley_cbp

Or install from a locally built wheel: pip install dist/stanley_cbp-0.1.X-py3-none-any.whl

## Environment setup (recommended)

For reproducible installations, this repository provides two Conda environment files:

`environment.yml` — for local machines and Jupyter-based workflows

`clusterEnvironment.yml` — for HPC or cluster environments

Users can create and activate an environment using either file, for example:

`conda env create -f environment.yml`
`conda activate stanley_env`

or, for cluster usage:

`conda env create -f clusterEnvironment.yml`
`conda activate stanley_env`

Once the environment is active, install STANLEY using one of the methods above.

## Using Stanley in Python

Example workflow:

**Import:**  
from stanley_cbp import runDetrendingModule, Stanley_FindPlanets, runAnalysisModule

**Detrending example:**  
`result_det = runDetrendingModule(SystemName="TIC260128333", DetrendingName="DemoDetrend", UseSavedData=0)`

**Search example:**  
`Stanley_FindPlanets(SearchName="DemoSearch", SystemName="TIC260128333", DetrendingName="DemoDetrend", totalSectors=1, currentSector=1)`

**Analysis example:**  
`analysis_out = runAnalysisModule(searchName="DemoSearch", systemName="TIC260128333", totalSectors=1)`

## Tutorials

A `Tutorials/` directory is provided with example Jupyter notebooks.  
These notebooks assume:

- a local **stanley_cbp** installation,  
- that the directory where the notebook is run will automatically function as the runtime workspace,  
- and that Stanley will generate all required folders (`LightCurves/`, `PlanetSearchOutput/`, `UserGeneratedData/`) as needed.

The tutorials demonstrate detrending, running the CBP search, interpreting outputs, and generating diagnostic figures.

## Licensing

This package is released under the **MIT License**.
