Metadata-Version: 2.1
Name: transitfetcher
Version: 1.0.1
Summary: A Python Package for Retrieving Exoplanet Transit Light Curves
Author-email: Chatdanai Sawangwong <chatdanai.saw@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/chatdanai-s/TransitFetcher
Project-URL: BugTracker, https://github.com/chatdanai-s/TransitFetcher/issues
Project-URL: Documentation, https://github.com/chatdanai-s/TransitFetcher
Keywords: astronomy,exoplanets,transit,light-curve,tess,kepler,astrophysics
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: lightkurve
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: matplotlib
Requires-Dist: requests

# TransitFetcher
An automated space-based (Kepler/TESS) exoplanet transit retrieval and preprocessing pipeline.

Simply provide a host star name (e.g. Kepler-10), then `TransitFetcher` automatically downloads and extracts
all individual transit light curves (from MAST via `lightkurve`) for known transiting planets in the system!

![Example image](img/combined_WASP148.png)

# Installation
Install the latest stable release from PyPI:
```bash
pip install transitfetcher
```

# Usage

TransitFetcher only has one function: `fetch()`, which retrieves and (optionally) plots various transit light curves. For example,

```python
from transitfetcher import fetch

fetch("WASP-148")
```

## Function Parameters

```python
fetch(
    target,
    output_root=None,
    includes=["Kepler", "TESS"],
    normalize_flux=False,
    plot_entire_lightcurve=True,
    plot_individual_transits=True,
    plot_folded_transits=True,
    plot_riverplot=True,
    generate_transitfit_csvs=False
)
```

| Parameter | Type | Default | Description | Notes |
|---|---|---|---|---|
| `target` | `str` | Required | Target name or identifier. | Do not include planet letters (e.g. `"Kepler-10"` NOT `"Kepler-10 b"`). |
| `output_root` | `str` or `Path` | `None` | Root directory for output files. | `None` defaults to the current working directory. |
| `includes` | `list[str]` | `["Kepler", "TESS"]` | Missions to include when searching for transit data. | Only accepts `"Kepler"` and/or `"TESS"`. |
| `normalize_flux` | `bool` | `False` | Prioritize flux-detrended data (by Savitzky-Golay filtering) when processing transits. | |
| `plot_entire_lightcurve` | `bool` | `True` | Generate unfolded light curve plots by quarter/sector. | |
| `plot_individual_transits` | `bool` | `True` | Generate plots for individual transit events. | |
| `plot_folded_transits` | `bool` | `True` | Generate phase-folded transit plots by quarter/sector. | Always uses detrended data |
| `plot_riverplot` | `bool` | `True` | Generate transit river plots by mission. | Always uses detrended data |
| `generate_transitfit_csvs` | `bool` | `False` | Generate configuration CSV files for `TransitFit`. | |

## Output

For each target, `TransitFetcher` creates a dedicated output directory containing the retrieved light curves, extracted transit events, plots, and other auxiliary files.
Directories containing planet-specific outputs (`folded_transit_plots`, `individual_transit_csv`, `individual_transit_plot`, and `transitfit_configs`)
are further organized into sub-directories for each known transiting planet in the system.

```text
TransitFetcher_<target>/
├── folded_transit_plots/       # Phase-folded light curves per planet (always detrended)
│   ├── <planet_1>/
│   ├── <planet_2>/
│   └── ...
├── individual_transit_csv/     # Individual transit CSVs (detrended if normalize_flux=True)
│   ├── <planet_1>/
│   ├── <planet_2>/
│   └── ...
├── individual_transit_plot/    # Individual transit plots (detrended if normalize_flux=True)
│   ├── <planet_1>/
│   ├── <planet_2>/
│   └── ...
├── lightcurve_plots/           # Full mission light curve plots (detrended if normalize_flux=True)
├── river_plots/                # River plots for each mission per planet (always detrended)
├── transitfit_configs/         # Configuration files for further TransitFit use
│   ├── <planet_1>/
│   ├── <planet_2>/
│   └── ...
├── <target>_lc_flattened.csv         # Combined detrended light curve
├── <target>_lc_unflattened.csv       # Combined original light curve
└── <target>_transit_ephemerides.csv  # Planetary parameters queried from exo.MAST
```

## Usage Notes
- `TransitFetcher` does **not** perform transit fitting or parameter inference of any kind.
It is intended for automatic extraction of individual transit events to be subsequently analyzed using
arbitrary methods and software, particularly geared towards transit timing variation (TTV) studies.
- `TransitFetcher` currently uses `lightkurve.SearchResult.download_all()` for MAST light curve downloads.
While direct bulk downloads via `astroquery.mast` may be supported in the future, `TransitFetcher` currently does not,
and so you may see yourself rate limited if you were to fetch many target light curves using a for loop.
- It is highly recommended to keep `normalize_flux` as `False` (default) to preserve original flux values.
`TransitFetcher` uses a Savitzky-Golay filter (polynomial degree 2) with a window length of at least
4x the transit duration or 25 hours (51 for Kepler and 751 for TESS), which may be unreliable for some transits.
Users should always manually inspect folded transit plots if `normalize_flux` is `True`.
<!--
# To-do
- [ ] Bulk TESS-Kepler MAST query download for `target` argument as list of planets
- [ ] In-code documentation
- [ ] Input checking/validation
- [ ] K2 mission support
-->
