preface-spearnet 2.0.0b2__tar.gz

preface_spearnet-2.0.0b2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 - Present: Chatdanai Sawangwong and contributors.
+
+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.

preface_spearnet-2.0.0b2/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.1
+Name: preface_spearnet
+Version: 2.0.0b2
+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.
+
+---
+
+## 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:
+```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-spearnet.readthedocs.io](https://preface-spearnet.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, 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: 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}
+}
+``` -->

preface_spearnet-2.0.0b2/README.md

@@ -0,0 +1,137 @@
+# 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.
+
+---
+
+## 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:
+```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-spearnet.readthedocs.io](https://preface-spearnet.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, 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: 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}
+}
+``` -->

preface_spearnet-2.0.0b2/preface/P1_Cutter.py

@@ -0,0 +1,89 @@
+# Part 4.1 of overall pipeline.
+# Takes in WorkingTEPSet, calculates exposure times, cadences and ranks for a chosen calibration telescope/filter combination.
+# This then provides the cut-off to be subsequently used in the wider pipeline.
+# This cut-off must be chosen by the user - at present, a physically-motivated cut is not possible.
+# Outputs a small .csv of D_min values for wider use.
+import pandas as pd
+import numpy as np
+
+#The central rank-making function.
+def RankMaker(CSV_core_folder, CSV_intermediate_folder,
+              scope_df, instrument, filter_name, run_mode, toggle_sky_noise, toggle_defocus, metric_mode, viable_cumulative_cut):
+
+    # Parameters for RankMaker for calibrating instruments
+    if run_mode == 'Spectral_Half_Well':
+        Inst_cal = 'VLT FORS2 (200kHz) 600RI+19'  # Calibrating instrument
+        Filter_cal = '600RI+19'
+        SkyNoise_cal = toggle_sky_noise
+        Defocus_cal = toggle_defocus
+
+    elif run_mode == 'IR_Half_Well':
+        Inst_cal = 'VLT KMOS_HK'
+        Filter_cal = 'HK'
+        SkyNoise_cal = True
+        Defocus_cal = toggle_defocus
+
+    else:  # Half_Well Run_Mode
+        Inst_cal = instrument
+        Filter_cal = filter_name
+        SkyNoise_cal = toggle_sky_noise
+        Defocus_cal = toggle_defocus
+
+    cal_idx = np.where(scope_df['Telescope'] == Inst_cal)[0][0]  # Index of calibrating Inst
+
+    sky_noise_text = 'Y-SkyNoise' if SkyNoise_cal else 'N-SkyNoise'
+    defocus_text = 'Y-Defocus' if Defocus_cal else 'N-Defocus'
+    calibrator_csv_path = (
+        CSV_intermediate_folder / "ranked_tep_sets"
+        / f"RankedTEPSet_{Inst_cal}_{Filter_cal}-band_for_{run_mode}_{sky_noise_text}_{defocus_text}.csv"
+    )
+    rankcut_csv_path = (
+        CSV_intermediate_folder / "minranks_cut_sets"
+        / f"minRanks_{Inst_cal}_{Filter_cal}-band_for_{run_mode}_{sky_noise_text}_{defocus_text}_{viable_cumulative_cut*100}%_cut.csv"
+    )
+    (CSV_intermediate_folder / "minranks_cut_sets").mkdir(parents=True, exist_ok=True)
+
+    # Run RankMaker on Calibrating instrument if configuration is different
+    different_calibrating_configuration = (Inst_cal != instrument) or (Filter_cal != filter_name) \
+                                       or (SkyNoise_cal != toggle_sky_noise) or (Defocus_cal != toggle_defocus)
+    
+    if different_calibrating_configuration == True:
+        import preface.P1_RankMaker as P1_RankMaker
+        print("[Cutter] Running RankMaker on calibrating instrument...")
+        P1_RankMaker.RankMaker(CSV_core_folder, CSV_intermediate_folder,
+                               scope_df, cal_idx, Inst_cal, Filter_cal, run_mode, SkyNoise_cal, Defocus_cal)
+
+    df_cal = pd.read_csv(calibrator_csv_path, skipinitialspace=True)
+
+
+    # 'Index' column is only there to make the CSV look like the legacy ver as much as possible.
+    # This is the list to store cut thresholds.
+    RMin_cols = ['Index', 'RMin_Rank', 'RMin_Habitable_Rank',
+                 'RMin_Multi_Transit_Rank', 'RMin_Multi_Transit_Habitable_Rank']
+    RMin_vals = [1]
+
+    def CumCutter(metric_col):
+        # Sort by chosen column (signal strength parameter), high to low.
+        df_cal_temp = df_cal.sort_values(by=metric_col, ascending=False)[[metric_col]]  # [[col]] keeps dj a dataframe
+        df_cal_temp.reset_index(inplace=True)
+        df_cal_temp['CumSum'] = df_cal_temp[metric_col].cumsum() # Cumulative sum calculation
+        df_cal_temp['CumSumFrac'] = df_cal_temp['CumSum'] / df_cal_temp['CumSum'].max()
+
+        df_cal_temp = df_cal_temp[df_cal_temp['CumSumFrac'] <= viable_cumulative_cut]
+        RMin = df_cal_temp[metric_col].min()
+        RMin_vals.append(RMin)
+    
+    # For loop on all metrics
+    for metric in ['Rank', 'Habitable_Rank', 'Multi_Transit_Rank', 'Multi_Transit_Habitable_Rank']:
+        CumCutter(metric)
+
+    
+    # Brings together into DataFrame and provides cutoff value
+    df = pd.DataFrame([RMin_vals], columns=RMin_cols)
+    Rmin = df[f'RMin_{metric_mode}'][0]
+
+    # Write to CSV.
+    df.to_csv(rankcut_csv_path, index=False)     
+    print(rf'[Cutter] {viable_cumulative_cut*100}% cuts for {Inst_cal}, {Filter_cal}-band for {run_mode}, {sky_noise_text}, {defocus_text} generated.')
+
+    return Rmin

preface_spearnet-2.0.0b2/preface/P1_ExoplanetseuImpactMerger.py

@@ -0,0 +1,52 @@
+# Part 2.2 of overall pipeline.
+# Further b-values can be retrieved from exoplanets.eu, particularly for new objects.
+
+import pandas as pd
+from preface.P1_ImpactMerger import BWriter
+
+# Main function
+
+def ExoeuImpacts(CSV_core_folder):
+    # Locate files
+    tep_with_exob_csv_path = CSV_core_folder / 'FullTEPSetWithExoOrgImpacts.csv'
+    exoplanets_eu_csv_path = CSV_core_folder / 'exoplaneteu_catalog.csv'
+    tep_with_allb_csv_path = CSV_core_folder / 'FullTEPSetWithAllImpacts.csv'
+
+
+    # Takes in FullTEPSet, processes names to find those with missing b.
+    df_tep_exob = pd.read_csv(tep_with_exob_csv_path)
+    df_tep_exob.insert(1, 'Planet_temp', df_tep_exob['Planet'])   # Temporary column
+
+    df_tep_exob['Planet'] = df_tep_exob['Planet'].replace({'-00':'-', '-0':'-',
+                                                           '_00':'_', '_0':'_'},
+                                                           regex=True)
+    df_tep_exob['Planet'] = df_tep_exob.apply(lambda row: BWriter(row), axis=1)
+    
+
+    # Takes in table of transiting planets from exoplanets.eu, processes names to find b values
+    colnames = ['name', 'impact_parameter']
+    df_eu = pd.read_csv(exoplanets_eu_csv_path, usecols=colnames)
+    df_eu.rename(columns={'name': 'Planet',
+                          'impact_parameter': 'Impact Parameter_from_eu'},
+                 inplace=True)
+
+    # This scheme is not perfect yet, needs polishing
+    df_eu['Planet'] = df_eu['Planet'].replace({'AU Mic ':'AU_Mic_',
+                                             'A b':'b', ' A':'', ' B':'', ' (AB)':'',
+                                             r'([A-Z]) ': r'\1_',
+                                             ' ':'',
+                                             'EPIC_22881391b':'EPIC_228813918b'
+                                             },
+                                             regex=True)
+
+
+    # Append impact parameter to missing values in original dataframe then export
+    df_tep_allb = pd.merge(df_tep_exob, df_eu, on='Planet', how='left')
+    df_tep_allb['Impact Parameter'] = df_tep_allb['Impact Parameter'].fillna(df_tep_allb['Impact Parameter_from_eu'])
+    df_tep_allb = df_tep_allb.drop(columns=['Planet', 'Impact Parameter_from_eu'])
+    df_tep_allb = df_tep_allb.rename(columns={'Planet_temp': 'Planet'})   # Recover old planet names  
+
+    # Reads back out with:
+    df_tep_allb.to_csv(tep_with_allb_csv_path, index=False)
+
+    print('[ExoplanetseuImpactMerger] Impact parameters from exoplanets.eu recovered.')

preface_spearnet-2.0.0b2/preface/P1_ImpactMerger.py

@@ -0,0 +1,59 @@
+# Part 2.1 of overall pipeline.
+# TEPCat does not store impact parameters, so they must be corralled from elsewhere.
+
+import pandas as pd
+
+# Small function to massage names such that both catalogues use same naming convention.
+def BWriter(row):
+    if row['Planet'][-1].isdigit() == True:
+        row['Planet'] = row['Planet'] + 'b'
+        
+    return row['Planet']
+
+# Main function
+def ExoOrgImpacts(CSV_core_folder):
+    # Locate files
+    fulltepset_csv_path = CSV_core_folder / 'FullTEPSet.csv'
+    exoorglist_csv_path = CSV_core_folder / 'ExoOrgList.csv'
+    tep_with_exoorg_csv_path = CSV_core_folder / 'FullTEPSetWithExoOrgImpacts.csv'
+
+
+    # Takes in all names in FullTEPSet and processes them.
+    df_fulltep = pd.read_csv(fulltepset_csv_path)
+    df_fulltep.insert(1, 'Planet_temp', df_fulltep['Planet'])   # Temporary column to be used in final planet name
+
+    # Setup planet column as key
+    df_fulltep['Planet'] = df_fulltep['Planet'].replace({'-00':'-', '-0':'-',
+                                                         '_00':'_', '_0':'_'},
+                                                         regex=True
+                                                         )
+    df_fulltep['Planet'] = df_fulltep.apply(lambda row: BWriter(row), axis=1)
+
+
+    # Takes in table of transiting planets from exoplanets.org
+    # exoplanets.org is a catalogue built by hand, so no auto-updater here.
+    # Also, exoplanets.org is not updated with planets published after June 2018
+    colnames = ['NAME', 'B']
+    df_exoorg = pd.read_csv(exoorglist_csv_path, usecols=colnames)
+    df_exoorg.rename(columns={'NAME': 'Planet', 'B': 'Impact Parameter'}, inplace=True)
+
+    # Process planet names before merging
+    df_exoorg['Planet'] = df_exoorg['Planet'].replace({'55 Cnc e':'55_Cnc_e', 'OGLE2':'OGLE',
+                                                       'BD +20 594': 'K2-56b', 
+                                                       r'([A-Z]) ': r'\1_',
+                                                       'A b':'b',
+                                                       ' ':''
+                                                       },
+                                                       regex=True
+                                                       )
+    
+
+    # Append impact parameter to original dataframe
+    df_combined = pd.merge(df_fulltep, df_exoorg, on='Planet', how='left')
+    df_combined = df_combined.drop('Planet', axis=1)                      # Recover old planet names
+    df_combined = df_combined.rename(columns={'Planet_temp': 'Planet'})  
+
+    # Export
+    df_combined.to_csv(tep_with_exoorg_csv_path, index=False)
+
+    print('[ImpactMerger] Impact parameters from exoplanets.org recovered.')