spino 0.3.0

SPINO (Software for exoPlanet vIsibility and Nightly Observations): a Tkinter GUI for scheduling exoplanet transit / eclipse phase-coverage observations

SPINO

Software for exoPlanet vIsibility and Nightly Observations

---

Overview

SPINO is a self-contained Tkinter desktop application for planning exoplanet transit / secondary-eclipse phase-coverage observations. It wraps a scientific scheduling pipeline (catalog loading, desert filtering, per-planet visibility, TSM/ESM ranking, telluric-overlap plots) behind an editable graphical interface. Every parameter that used to live in a Python config file is now a form field.

The widget/panel/theming layer is reused from GUIBRUSHR, an earlier toolkit by the same author; the scheduling pipeline is bundled in src/spino/pipeline/. The whole thing is standalone: all Python modules and data files it needs are vendored into the package, so it runs offline out of the box.

Disclaimer. SPINO is a first-look, organizational aid, not an authoritative source. It turns a large catalog into a coherent, homogeneous shortlist so you can assemble a proposal quickly, but every value it reports (ephemerides, visibility windows, event durations, metrics) must be verified independently and carefully for each target before use.

---

Table of Contents

• Features
• Prerequisites
• Installation
• Usage
• Documentation
• Architecture
• Troubleshooting
• Support
• License & Attribution
• Citation
• Acknowledgments

---

Features

• Every config parameter is editable in the GUI: catalog source, desert / extra filters, observatory (telescope + instrument + site), proposal window, observing & event-coverage constraints, hand-entered custom planets, the telluric-overlap plot grid, and all output / landscape settings.
• One-click run of the pipeline in a background subprocess, with the live log streamed into the window and a Stop button.
• Generated PDFs / CSVs listed in the app; double-click to open them in your system viewer.
• Save / Load presets as JSON, and Reset to defaults.
• Bundled NASA Exoplanet Archive catalog cache, desert-boundary / KDE aux files, and a sky-transmission FITS, so it runs offline out of the box.

---

Prerequisites

• Python 3.10+

• Tkinter ships with most Python builds (including the conda-forge Python). There is no tkinter package on PyPI, so pip install tkinter does not work; if import tkinter fails, install it with your package manager:

  conda install tk                 # conda
  sudo apt install python3-tk      # Debian / Ubuntu
  sudo dnf install python3-tkinter # Fedora
  

---

Installation

Option A: Install with conda (recommended)

The conda-forge Python 3.10 already bundles Tkinter, so nothing extra is needed:

conda create -n spino_env python=3.10
conda activate spino_env
pip install spino

Option B: Install from PyPI into an existing environment

pip install spino

Option C: Clone and install in editable mode (for development)

git clone https://github.com/francescoa97outlook/SPINO
cd SPINO
python -m venv .venv && source .venv/bin/activate   # or a conda env
pip install -e .

This installs the spino console entry point and all Python dependencies.

---

Usage

Launch the GUI

spino                # console entry point (after pip install)
# or, from a source checkout:
python -m spino

Headless run (quickest smoke test, no GUI)

python -m spino.runner path/to/settings.json

---

Documentation

Full documentation is hosted on Read the Docs: spino-exoplanets.readthedocs.io.

The sources live in docs/source/:

Doc	Contents
installation.md	Requirements, venv, python3-tk, editable install
usage.md	Tab-by-tab walkthrough, running, presets, outputs
configuration.md	Reference for every configuration parameter
architecture.md	How the GUI, runner subprocess and pipeline fit together
credits.md	GUIBRUSHR reuse and licensing

To build the documentation locally:

./build_docs.sh
# then open docs/build/html/index.html

---

Architecture (at a glance)

GUI (app.py + panels/)  --collect-->  settings.json
        |                                   |
        |  subprocess: python -m spino.runner settings.json
        v                                   v
   log pane  <--stdout--  runner.py  --overlay-->  pipeline/phase_config
                                |                          |
                                +---> pipeline/phase_scheduler.main()
                                              |
                                        OUTPUT_DIR/*.pdf, *.csv

---

Troubleshooting

ModuleNotFoundError: No module named 'tkinter'

• Tkinter is not bundled on some Linux Python builds. Install it with sudo apt install python3-tk (Debian/Ubuntu) or the equivalent for your distribution.

Import errors after installation

pip install -e . --force-reinstall

The GUI opens but the catalog is empty

• SPINO ships with a cached NASA Exoplanet Archive catalog. If you switched the catalog source, ensure network access or revert to the bundled cache.

---

Support

For questions, bug reports, or technical assistance, please open an issue on the GitHub repository or contact:

Francesco Amadori 📧 [e-mail]

---

License & Attribution

SPINO is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License v3.0 or later (see LICENSE).

It reuses GUI widget code from GUIBRUSHR, which is GPLv3; as a derivative work SPINO is therefore also GPLv3. See docs/source/credits.md and the GUIBRUSHR project.

---

Citation

If you use SPINO in your research, please cite this repository: github.com/francescoa97outlook/SPINO.

---

Acknowledgments

SPINO relies on several open-source packages, including NumPy, SciPy, Matplotlib, pandas, Astropy, and astroquery, and reuses the GUI toolkit from GUIBRUSHR, an earlier toolkit by the same author.