Metadata-Version: 2.4
Name: astrosequence-explorer
Version: 1.0.1
Summary: A cross-platform GUI for full-field astronomical time-series photometry, variable-star candidate detection, plate solving, and Gaia/VSX catalog matching.
Author: Daniele Gasparri
Keywords: astronomy,photometry,variable stars,time-series,light curves,aperture photometry
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Intended Audience :: Science/Research
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: astropy>=6.0
Requires-Dist: matplotlib>=3.8
Requires-Dist: scipy>=1.11
Requires-Dist: photutils>=1.11
Requires-Dist: astroquery>=0.4.7
Requires-Dist: scikit-learn>=1.8.0
Requires-Dist: joblib>=1.3
Provides-Extra: gui
Requires-Dist: FreeSimpleGUI>=5.0; extra == "gui"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Dynamic: license-file

# AstroSequence Explorer

📖 **Author:** Daniele Gasparri  
📅 **Latest Release:** July 2026  

![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)
[![License](https://img.shields.io/badge/license-see%20LICENSE-blue)](./LICENSE)

**AstroSequence Explorer is a cross-platform GUI application for semi-automatic full-field time-series photometry of astronomical point sources. It detects stars in calibrated FITS image sequences, extracts aperture-photometry light curves, ranks candidate variables, and performs Gaia/VSX catalog matching.**  
It is particularly suited for astrophotographers who want an easy tool to explore the scientific content of their imaging sequences. 

<br>

<img alt="main gui" src="https://github.com/user-attachments/assets/b27c1f96-e378-4de3-a9fb-b78177cd6732" />

*Guided analysis workflow: load a sequence, set automatic parameters, run the full-field variability search, and inspect candidates.*

<br>

<img alt="candidate review" src="https://github.com/user-attachments/assets/26187b4c-bbd4-4a7d-818e-af6637017e99" />


*Candidate review panel with light curves, reference-field cutouts, manual labels, ML suggestions, and catalog information.*


## What AstroSequence Explorer does

AstroSequence Explorer turns a calibrated and aligned astronomical image sequence into a searchable field-wide time-domain dataset. Instead of measuring one target at a time, it performs aperture photometry for all detected point sources, builds light curves, ranks variability candidates, and helps the user identify known or new variable stars, eclipsing systems, and transit-like events.

The program is designed for observers who acquire long FITS sequences of the same field and want a practical way to answer questions such as:

- Which stars in this field are variable?
- Are there transit-like or eclipse-like dips in the sequence?
- Are my candidates already known VSX or Gaia DR3 variables?
- Which candidates deserve manual inspection or follow-up observations?


## Features

- **Guided full-field analysis workflow**
  - Load a folder of calibrated and aligned FITS images.
  - Run the complete workflow by pressing only two buttons.

- **Point-source detection and all-star aperture photometry**
  - Automatic source detection on the reference image.
  - Aperture and sky-annulus photometry for all retained sources.
  - Centroid recentering and frame-shift handling.
  - Support for monochrome data, OSC/color-camera data, debayered images, and extracted color-channel sequences.

- **Candidate ranking for variability and transit-like events**
  - Ranking based on robust photometric metrics such as RMS excess, amplitude, and dip score.

- **Machine-learning assistance**
  - Built-in ML suggestions to help prioritize candidates.

- **Plate solving and catalog matching**
  - Local ASTAP plate solving from the GUI.
  - Gaia source matching.
  - Gaia DR3 variability matching.
  - VSX known-variable matching.
  - Optional local VSX catalog support for more reliable and faster matching.


## Recommended input data

AstroSequence Explorer expects a sequence of **calibrated and aligned FITS images** of the same field.

AstroSequence Explorer is not intended to replace a raw-image calibration pipeline. Bias/dark/flat correction, bad-pixel correction, and image alignment should be performed before loading the sequence.
To maximize the photometric information contained in your images, you can try the reduction and alignment module of [ExoPhotoCurve]([https://www.hnsky.org/astap.htm](https://github.com/danielegasparri/ExoPhotoCurve)) software, instead of relying on aesthetically optimized commercial software such as Deep Sky Skacker or PixInsight.


The program can work with:

- monochrome-camera FITS sequences;
- color-camera raw/CFA monochrome FITS sequences;
- debayered or channel-extracted OSC sequences;
- sequences with missing frame numbers;
- sequences without progressive filename numbering, provided that valid `DATE-OBS` timestamps are present in the FITS.

For best results, use sequences with stable pointing, good alignment, and enough frames to distinguish real variability from noise or artifacts, from the same observing night.
If you are working with a sequence taken in different nights, be aware that the physical constraints and machinel-learning model for variability detection and ranking, may not work properly. For optimal results, please use sequences taken during one single night of observation. 

## System Requirements

- Python 3.10+
- Screen resolution of at least 1600×900 px. Optimal resolution: 1920×1080
- Recommended for plate solving: [ASTAP](https://www.hnsky.org/astap.htm) with a suitable local star database (D50 works fine)
- Recommended for fast variable matching: a local copy of the [International Variable Star Index (VSX) database](https://cdsarc.cds.unistra.fr/cgi-bin/cat/B/vsx#/browse), via FTP and in fits format. 
- Main Python dependencies include: `numpy`, `astropy`, `matplotlib`, `scipy`, `photutils`, `astroquery`, `scikit-learn`, `joblib`, and `FreeSimpleGUI`

A standalone Windows installer is also available from the official GitHub Releases page.


## Installation

You can install **AstroSequence Explorer** using `pip`:

```bash
pip install astrosequence-explorer
```

Then run:

```bash
astrosequence-explorer
```


On Windows, you just download the installer, install the app and run it.


## Quick Start

1. Open AstroSequence Explorer.
2. Select the folder containing your calibrated and aligned FITS sequence.
3. Click **Load sequence**.
4. Click **Set automatic parameters**.
5. Optional: enable ASTAP plate solving and Gaia/VSX catalog matching.
6. Click **Run full analysis**.
7. Inspect the ranked candidates in the **Candidate review** tab.
8. Click candidates to preview their light curves and reference-field cutouts.
9. Perform a deep search using all the available online catalogs via right click on the selected candidate
10. Assign manual labels such as **Variable**, **Transit/eclipse**, **Uncertain**, or **Noise/artifact**.
11. Export the candidate tables, plots, and review files.


## Quick start with an example dataset

An example dataset is distributed from the GitHub Releases page. After downloading and unzipping it:

- Open AstroSequence Explorer.
- Select the example FITS sequence folder.
- Click **Load sequence**.
- Click **Set automatic parameters**.
- Keep the default presets.
- Optional: enable **Plate solving with ASTAP** and **Match Gaia and VSX catalogs after analysis**.
- Click **Run full analysis**.
- When the analysis finishes, the **Candidate review** will open automatically and you can inspect the ranked candidates.


## How candidate ranking should be interpreted

AstroSequence Explorer is designed to find and prioritize interesting candidates, not to make final scientific classifications automatically.

The ranking combines interpretable photometric indicators such as scatter excess, robust amplitude, and dip-like behavior. The ML suggestion is an additional prioritization aid. A source marked as ML-interesting is worth inspecting first, while ML-uncertain candidates should not be ignored when the light curve or catalog information looks promising.

All candidates should be visually checked, especially in crowded fields, near the image border, close to saturated stars, or in sequences affected by clouds, tracking issues, meridian flips, or variable background.


## Plate solving and catalog matching

Catalog matching requires sky coordinates. AstroSequence Explorer can use an existing celestial WCS in the FITS files, or it can solve the reference frame locally with ASTAP.

The ASTAP workflow is designed to be robust for common amateur and professional observing setups, including images produced from OSC/color cameras. When the FITS header gives a misleading FOV, such as for extracted Bayer/green-channel images, AstroSequence Explorer automatically tests alternative FOV hypotheses and updates the displayed field size from the solved WCS.

After a valid WCS is available, AstroSequence Explorer can match candidates against:

- Gaia sources;
- Gaia DR3 variability information;
- VSX known variables;
- an optional local VSX catalog/index (recommended).

Catalog matches are meant to help interpretation. A missing catalog match does not prove that a candidate is new, and a loose catalog match should always be checked manually.
You can perform a deep catalog search for a selected candidate by right click --> Deep catalog search. This will scan the main catalogs for a match, not just GAIA and VSX. If no match is found and the star exhibits clear variability, it is a new candidate variable star. In this case, a careful deep manual search and follow-up observations will be necessary to confirm its nature.

## Output files

AstroSequence Explorer writes its products inside an output folder associated with the analyzed sequence. Depending on the workflow, outputs may include:

- detected-source tables;
- photometry summaries;
- all-star light-curve tables;
- candidate ranking tables;
- candidate review tables;
- ML candidate-feature tables;
- candidate preview plots;
- RMS-versus-magnitude plots;
- WCS-solving diagnostics;
- catalog-match information.

These files are intended to make the analysis reproducible and to allow further inspection with external tools.


## Notes and limitations

- AstroSequence Explorer expects calibrated and aligned FITS images.
- It is optimized for point sources. Extended objects and very crowded fields require caution.
- Catalog queries depend on online services unless a local catalog is used.
- ML suggestions are not scientific classifications; they are a prioritization tool for human review.
- Final candidate confirmation requires independent checks and, when appropriate, follow-up observations.


## License

AstroSequence Explorer is distributed under the license included in the `LICENSE` file. Please check the repository license before using, redistributing, or modifying the software.


## Contact & Contributions

Found a bug? Want to suggest a feature?  
Drop me an email!  
Contact: Daniele Gasparri – daniele.gasparri@gmail.com  
Take a look also at my website, if you are interested in astronomy: https://www.danielegasparri.com/ 
