transitfetcher 1.0.0__tar.gz

transitfetcher-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chatdanai Sawangwong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

transitfetcher-1.0.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.1
+Name: transitfetcher
+Version: 1.0.0
+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!
+
+# 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("Kepler-10")
+```
+
+## 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
+- [ ] Input checking/validation
+- [ ] K2 mission support

transitfetcher-1.0.0/README.md

@@ -0,0 +1,97 @@
+# 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!
+
+# 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("Kepler-10")
+```
+
+## 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
+- [ ] Input checking/validation
+- [ ] K2 mission support

transitfetcher-1.0.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=61.0,<69.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "transitfetcher"
+version = "1.0.0"
+description = "A Python Package for Retrieving Exoplanet Transit Light Curves"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+
+keywords = [
+  "astronomy",
+  "exoplanets",
+  "transit",
+  "light-curve",
+  "tess",
+  "kepler",
+  "astrophysics"
+]
+
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+]
+
+authors = [
+  { name = "Chatdanai Sawangwong", email = "chatdanai.saw@gmail.com" }
+]
+
+dependencies = [
+  "lightkurve",
+  "numpy",
+  "pandas",
+  "matplotlib",
+  "requests"
+]
+
+[project.urls]
+Homepage = "https://github.com/chatdanai-s/TransitFetcher"
+BugTracker = "https://github.com/chatdanai-s/TransitFetcher/issues"
+Documentation = "https://github.com/chatdanai-s/TransitFetcher"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["transitfetcher*"]
+exclude = ["__pycache__", "tests", "docs"]

transitfetcher-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

transitfetcher-1.0.0/tests/test.py

@@ -0,0 +1,12 @@
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from transitfetcher import fetch
+
+targets = ["Kepler-522"]
+output_root = r'C:\Users\WBS\Documents\TransitFetcher_test_output'
+
+for target in targets:
+    fetch(target, output_root=output_root, includes=['Kepler', 'TESS'],
+          normalize_flux=False, generate_transitfit_csvs=True)

transitfetcher-1.0.0/transitfetcher/__init__.py

@@ -0,0 +1,75 @@
+from . import pipeline as tf_pipeline
+import pandas as pd
+
+def 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):
+    
+    print(f'===== TransitFetcher started for {target} =====')
+
+    # Locate output folder
+    output_folder = tf_pipeline.get_output_folder(target, output_root)
+
+    # Fetch transit ephmerides from exo.mast
+    tf_pipeline.fetch_transit_ephemerides(target, output_folder)
+
+    # Fetch light curves from MAST via lightkurve
+    if isinstance(includes, str):
+        includes = [includes]
+    for mission in includes:
+        tf_pipeline.fetch_lightcurves(target, mission, output_folder)
+
+    # Concatenate fetched lightcurves
+    lc_folder = output_folder / "lightcurves_flattened"
+    lc_list = [f.name for f in lc_folder.glob("*.csv")]
+    if (len(lc_list) == 0):
+        print(f'===== TransitFetcher completed for {target} (No lightcurves downloaded) =====')
+        return
+    
+    tf_pipeline.concatenate_lightcurves(lc_list, output_folder)
+
+    # Import concatenated lightcurves
+    if (normalize_flux == False):
+        ulc = pd.read_csv(output_folder / f"{target}_lc_unflattened.csv")
+    else:
+        ulc = None
+    
+    if (normalize_flux == True) or (plot_folded_transits == True) or (plot_riverplot == True):
+        flc = pd.read_csv(output_folder / f"{target}_lc_flattened.csv")
+    else:
+        flc = None
+
+    lcs = {'ulc': ulc, 'flc': flc}  # Store as dict
+
+    # Plot lightcurves by quarter/sector
+    if plot_entire_lightcurve == True:
+        tf_pipeline.plot_lightcurves(target, lcs, normalize_flux, output_folder)
+    
+    # Iterate per planet in system
+    planet_df = pd.read_csv(output_folder / f"{target}_transit_ephemerides.csv")
+    for _, row in planet_df.iterrows():
+        # Terminate immediately if transit doesn't exist 
+        if row["transit_flag"] == False:
+            continue
+
+        # Fetch individual transits and optionally make diagonostic plots
+        tf_pipeline.fetch_individual_transits(lcs, normalize_flux, row, output_folder,
+                                              plot_individual_transits,
+                                              plot_folded_transits)
+
+        # River plot (Useful for large TTVs)
+        if plot_riverplot == True:
+            tf_pipeline.plot_river(flc, row, output_folder)
+
+        # Generate TransitFit configuration files
+        if generate_transitfit_csvs == True:
+            tf_pipeline.create_transitfit_configs(row, output_folder)
+
+    print(f'===== TransitFetcher completed for {target} =====\n')
+    return

transitfetcher-1.0.0/transitfetcher/misc.py

@@ -0,0 +1,16 @@
+import shutil
+from pathlib import Path
+import lightkurve as lk
+
+
+def clean_lightkurve_cache():
+    """
+    Deletes the entire Lightkurve download cache.
+    """
+    cache_dir = Path(lk.config.get_cache_dir())
+
+    if cache_dir.exists():
+        shutil.rmtree(cache_dir)
+        print(f"Deleted Lightkurve cache: {cache_dir}")
+    else:
+        print("Lightkurve cache does not exist.")