https://github.com/codebypinar/interstellar-ml-3i-atlas
Physics-aware ML analysis of 3I/ATLAS (photometry + spectroscopy).
https://github.com/codebypinar/interstellar-ml-3i-atlas
3i-atlas astronomy astrophysics interstellar-object lomb-scargle machine-learning photometry physics-informed plotly python reflectance-spectra reproducible-science research spectroscopy streamlit time-series
Last synced: about 1 month ago
JSON representation
Physics-aware ML analysis of 3I/ATLAS (photometry + spectroscopy).
- Host: GitHub
- URL: https://github.com/codebypinar/interstellar-ml-3i-atlas
- Owner: CodeByPinar
- Created: 2025-12-22T11:24:30.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2025-12-22T11:45:28.000Z (about 1 month ago)
- Last Synced: 2025-12-23T22:45:26.721Z (about 1 month ago)
- Topics: 3i-atlas, astronomy, astrophysics, interstellar-object, lomb-scargle, machine-learning, photometry, physics-informed, plotly, python, reflectance-spectra, reproducible-science, research, spectroscopy, streamlit, time-series
- Language: Python
- Homepage: https://interstellar-ml-3i-atlas.streamlit.app/
- Size: 43.9 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# interstellar-ml-3I-ATLAS
Physics-aware multi-modal analysis of **3I/ATLAS** using:
- ATLAS light curve photometry (`data_raw/ATLAS_light_curve.npy`)
- Reflectance spectrum (`data_raw/ATLAS_reflectivity_spectrum.csv`)
This repo is organized as *research software*:
- **Reusable core package** under `src/interstellar_ml/`
- **Config-driven CLI** via `main.py` (Typer)
- **Streamlit UI** in `ui/app.py` calling the same core modules (no duplicated logic)
---
## What you can do
- Validate raw datasets and view warnings
- Deterministic preprocessing with content-addressed caching (`data_processed/`)
- Light curve analysis:
- Lomb–Scargle periodogram
- Phase folding
- Scientific diagnostics (magnitude histogram, cadence Δt histogram, binned phase curve, residuals)
- Spectrum analysis:
- Continuum removal
- Global spectral slope estimate
- Scientific diagnostics (smoothing, derivative, linear-fit overlay)
- Run experiments and browse artifacts under `runs/`
---
## Quickstart (Windows / PowerShell)
Create an environment and install dependencies:
```powershell
python -m venv .venv
\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt
pip install -e .
```
Run a minimal analysis from the CLI:
```powershell
python main.py validate-data --config configs/datasets/atlas_3i.yaml
python main.py preprocess --config configs/datasets/atlas_3i.yaml
python main.py analyze-lightcurve --config configs/datasets/atlas_3i.yaml
python main.py analyze-spectrum --config configs/datasets/atlas_3i.yaml
```
Launch the UI:
```powershell
python -m streamlit run ui/app.py
```
---
## Configuration
Default dataset config:
- `configs/datasets/atlas_3i.yaml`
- Outputs:
- processed cache: `data_processed/`
- run artifacts: `runs/`
---
## Project layout
```text
.
├─ src/interstellar_ml/ # Core package (shared by CLI + UI)
│ ├─ analysis/ # Light curve / spectrum analysis utilities
│ ├─ data/ # Dataset loaders + types
│ ├─ preprocessing/ # Cache + preprocessing pipeline
│ ├─ experiments/ # Experiment runner stub
│ └─ viz/ # Plotly helpers
├─ configs/ # YAML configs (dataset + experiments)
├─ data_raw/ # Immutable source datasets
├─ data_processed/ # Hashed, deterministic derived products
├─ runs/ # Reproducible run directories (metrics/logs/figures)
└─ ui/app.py # Streamlit UI
```
---
## Reproducibility rules
- **Raw data is immutable**: keep source files under `data_raw/` unchanged.
- **Derived products are cached**: preprocessing outputs are stored under `data_processed/` with a content hash.
- **Runs are logged**: experiment outputs are written under `runs/`.
---
## Troubleshooting
### `ModuleNotFoundError: interstellar_ml` / import errors in Streamlit
Most commonly, Streamlit is running with the wrong interpreter.
Use the project virtual environment and run Streamlit via Python:
```powershell
\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
pip install -e .
python -m streamlit run ui/app.py
```
### `streamlit run app.py` fails
The UI entrypoint is `ui/app.py`:
```powershell
python -m streamlit run ui/app.py
```