Metadata-Version: 2.4
Name: disco-astronomy
Version: 1.2.5
Summary: Deprojection Image Software for Circumstellar Objects
Author-email: astrojorgeluis <jorge.guzman.l@usach.cl>
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.110.0
Requires-Dist: uvicorn[standard]>=0.29.0
Requires-Dist: python-multipart
Requires-Dist: astropy>=6.0.0
Requires-Dist: scipy>=1.11.0
Requires-Dist: matplotlib>=3.8.0
Requires-Dist: astroquery>=0.4.7
Requires-Dist: numpy<2.0.0
Requires-Dist: torch>=2.0.0
Requires-Dist: tqdm>=4.66.0

<p align="center">
  <img src="https://raw.githubusercontent.com/astrojorgeluis/disco-astronomy/main/DISCO_Source_Git/assets/disco_banner.png" alt="DISCO Logo" width="600"/>
</p>

<h1 align="center">DISCO</h1>
<h3 align="center">Deprojection Image Software for Circumstellar Objects</h3>

<p align="center">
  A hybrid pipeline for the analysis and physical characterization of protoplanetary disks from ALMA FITS data.
</p>

<p align="center">
  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.9+-3776AB?style=flat&logo=python&logoColor=white"/></a>
  <a href="https://pytorch.org/"><img src="https://img.shields.io/badge/PyTorch-CNN-EE4C2C?style=flat&logo=pytorch&logoColor=white"/></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg"/></a>
  <a href="https://pypi.org/project/disco-astronomy/"><img src="https://img.shields.io/badge/PyPI-disco--astronomy-blue?style=flat&logo=pypi&logoColor=white"/></a>
  <a href="https://doi.org/10.5281/zenodo.19999239"><img src="https://img.shields.io/badge/DOI-10.5281%2Fzenodo.19999239-blue?style=flat&logo=doi&logoColor=white"/></a>
  <a href="https://astrojorgeluis.github.io/disco-astronomy/"><img src="https://img.shields.io/badge/docs-online-purple?style=flat&logo=readthedocs&logoColor=white"/></a>
</p>

> ⚠️ **Work in Progress** — DISCO is in active early development. Features and interfaces may change between releases.

---

## Table of Contents

- [Overview](#overview)
- [Citation](#citation)
- [Key Features](#key-features)
- [Two Modes of Operation](#two-modes-of-operation)
- [Installation](#installation)
- [GUI Workflow](#gui-workflow)
  - [Step-by-Step Guide](#step-by-step-guide)
  - [Toolbar Reference](#toolbar-reference)
  - [View Modes](#view-modes)
  - [Analysis Tools](#analysis-tools)
  - [Display Configuration](#display-configuration)
  - [Export & Session Management](#export--session-management)
- [CLI Pipeline](#cli-pipeline)
  - [Usage Examples](#usage-examples)
  - [CLI Reference](#cli-reference)
- [Tech Stack](#tech-stack)
- [License](#license)
- [Support & Contact](#support--contact)

---

## Overview

DISCO is an open-source tool for the interactive and automated analysis of protoplanetary disk observations. It combines a convolutional neural network (**DiscoNet**) for rapid geometric parameter prediction with a hybrid optimization strategy, enabling robust deprojection and radial profile extraction from FITS images.

DISCO bridges scientific Python libraries with a modern web interface, offering two complementary modes of operation: a **GUI** for interactive exploration and a **CLI pipeline** for reproducible batch processing.

📖 **Full documentation:** [astrojorgeluis.github.io/disco-astronomy](https://astrojorgeluis.github.io/disco-astronomy/)

---

## Citation

If you use DISCO in your research, please cite the associated Zenodo record:

Guzmán-Lazo, J. L. (2026). *DISCO: Deprojection Image Software for Circumstellar Objects* (v1.2.5). Zenodo. https://doi.org/10.5281/zenodo.19999239

### BibTeX
```bibtex
@software{guzman_lazo_2026_19999239,
  author       = {Guzmán-Lazo, Jorge Luis},
  title        = {DISCO: Deprojection Image Software for
                   Circumstellar Objects
                  },
  month        = august,
  year         = 2026,
  publisher    = {Zenodo},
  version      = {v1.2.5},
  doi          = {10.5281/zenodo.19999239},
  url          = {https://doi.org/10.5281/zenodo.19999239},
}
```

## Acknowledgements

DISCO was developed by **Jorge Luis Guzmán-Lazo** within the [YEMS Millennium Nucleus](https://www.milenioyems.cl/) under the supervision of **Sebastián Pérez** and **Camilo González-Ruilova**.

---

## Key Features

- **DiscoNet (CNN)** — Predicts inclination, position angle, and center offsets from a 128×128 multi-channel crop (intensity + elliptical beam + scale). Shipped weights (v1.2.5) are trained on **20k synthetic** disks.
- **Hybrid Optimization** — CNN prior seeds a differential-evolution + **L-BFGS-B** refinement of a geometric loss on the real FITS image (CLI).
- **Radial Profiles** — Deprojection and azimuthally averaged profiles, with optional beam homogenization for multi-band groups.
- **Dual Visualization** — GUI with Cartesian / polar views and interactive ellipse overlay.
- **Batch CLI** — `disco-start` processes one or many targets; `-y` for non-interactive runs.
- **SIMBAD / Gaia** — GUI SIMBAD metadata; CLI Gaia DR3 proper-motion registration across epochs.
- **CSV Export** — Geometry and radial profiles (`--csv on`).

The plot annotation `i = … ± …` uses a **loss-curvature** estimate (`estimate_geometry_errors`), not a literature 1σ. Empirical accuracy is validated against published geometries (e.g. DSHARP).

---

## Two Modes of Operation

| Feature | CLI Pipeline (`disco-start`) | GUI (`disco-start gui`) |
|---|:---:|:---:|
| DiscoNet (CNN) geometry | ✅ | ❌ |
| Interactive visualization | ❌ | ✅ |
| Batch processing | ✅ | ❌ |
| Multi-band support | ✅ | ❌ |
| Beam homogenization | ✅ | ❌ |
| SIMBAD query | ❌ | ✅ |
| Session save / restore | ❌ | ✅ |
| Ease of use | Moderate | High |

The **GUI** is recommended for exploratory analysis and first-time users. The **CLI** is designed for reproducible, automated pipelines.

---

## Installation

> **Recommended:** Use a dedicated virtual environment to avoid dependency conflicts.

```bash
# 1. Create and activate a virtual environment
python -m venv disco-env
source disco-env/bin/activate        # Linux / macOS
disco-env\Scripts\activate           # Windows

# 2. Install DISCO from PyPI
pip install disco-astronomy

# 3. Verify the installation
disco-start --help
```

📦 Available on PyPI: [pypi.org/project/disco-astronomy](https://pypi.org/project/disco-astronomy/)

To keep DISCO up to date:

```bash
pip install --upgrade disco-astronomy
```

### Dependencies

All dependencies are resolved automatically by pip:

| Package | Min. Version | Role |
|---|---|---|
| `fastapi` | ≥ 0.110.0 | HTTP backend for the GUI server |
| `uvicorn[standard]` | ≥ 0.29.0 | ASGI server |
| `python-multipart` | — | File upload support |
| `astropy` | ≥ 6.0.0 | FITS I/O, WCS, coordinate transforms |
| `scipy` | ≥ 1.11.0 | Numerical optimization, signal processing |
| `matplotlib` | ≥ 3.8.0 | Scientific figure rendering |
| `astroquery` | ≥ 0.4.7 | Gaia DR3 and SIMBAD queries |
| `numpy` | < 2.0.0 | Array operations (pinned for compatibility) |
| `torch` | ≥ 2.0.0 | DiscoNet CNN inference |
| `tqdm` | ≥ 4.66.0 | CLI progress reporting |

---

## GUI Workflow

Launch the interactive web interface with:

```bash
disco-start gui
```

This starts a local server on the first free port starting at 8000 and opens a browser tab automatically. Check the terminal for the URL (for example `http://localhost:8000`, or `8001` if 8000 is already in use).

**From a source checkout** (editable install), build the frontend once before the first GUI launch:

```bash
cd DISCO_Source_Git/client
npm ci
npm run build          # writes disco/static/ (required)
disco-start gui
```

If you see `GUI static assets not found`, the `npm run build` step is missing.

![GUI Screenshot](https://raw.githubusercontent.com/astrojorgeluis/disco-astronomy/main/DISCO_Source_Git/assets/gui_screenshot.png)

### Step-by-Step Guide

A typical session follows these steps:

**1. Load a FITS file**
Click the **folder icon** in the toolbar and select your `.fits` file. The image will appear in the viewer and the FITS header will populate automatically in the metadata panel.

**2. Adjust the disk geometry**
In the **CONTROLS** panel on the left, use the sliders to set the initial geometric parameters:

- **Inclination** — disk inclination in degrees (0° = face-on, 90° = edge-on).
- **Position Angle** — orientation of the disk major axis in degrees.
- **Radius Out** — estimated outer disk radius in arcseconds.
- **Center X / Y** — pixel coordinates of the disk center (auto-initialized to the image midpoint).

Activate the **Ellipse Tool** in the toolbar to display the geometry overlay on the image. As you move the sliders, the ellipse updates live so you can visually align it with the disk before running the pipeline.

**3. Run the pipeline**
Click **RUN PIPELINE**. DISCO computes the deprojected image, azimuthally-averaged radial profile, cumulative flux curve, and Gaussian ring fit for the current parameters.

**4. Auto-tune the geometry (optional)**
Click **Auto-Tune Geometry** in the analysis panel to refine inclination, position angle, and center from the current sliders. This GUI path runs a coarse grid search followed by a local **L-BFGS-B** fit of the geometric loss (center moves only within a small pixel window). It is a helpful starting point, **not** a guaranteed global optimum: low-inclination disks, weak rings, or a poor seed can leave a local minimum. Check the ellipse by eye and adjust manually if needed. The stronger CNN + differential-evolution hybrid lives in the **CLI**, not in this button.

**5. Explore the results**
Switch between **Deprojection / Model / Residuals / Polar** views to inspect different representations of the disk. Activate the **Inspector** tool and hover over the image to probe the radial profile in real time. Drag on the profile chart to define a fitting range for Gaussian ring analysis.

**6. Export**
Download the radial profile as CSV, save the current view as a FITS file, or open the **Matplotlib Widget** for a publication-ready figure. Use **Save Session** to preserve your parameters for later.

---

### Toolbar Reference

![GUI Screenshot Tools](https://raw.githubusercontent.com/astrojorgeluis/disco-astronomy/main/DISCO_Source_Git/assets/gui_screenshot_tools.png)

The toolbar provides file management and viewer interaction controls. The active mode is highlighted with a purple background.

| Icon | Name | Description |
|:---:|---|---|
| 📁 | **Open File** | Opens a file picker to load a `.fits` image or a previously saved `.json` session file. |
| 💾 | **Save Session** | Saves current parameters (inclination, PA, radius, center) and the active filename to a `.json` file for later restoration. |
| ⛶ | **Fullscreen** | Expands the viewer panel to fill the browser window. |
| ✕ | **Close** | Clears the currently loaded file and resets the interface. |
| ◎ | **Ellipse Tool** | It allows you to manipulate the shape of the ellipse. The ellipse reflects the current inclination, position angle, and outer radius in real time as you adjust the sliders and/or move the ellipse control. Use it as a visual guide before running the pipeline. |
| 🖐 | **Pan** | Switches to pan/drag mode for navigating across large images. |
| ⊕ | **Inspector** | Enables the Cursor Probe. Hovering over the image synchronizes the crosshair position with the 1D radial profile chart and shows Radius, Intensity (K), and X/Y sky offsets in real time. |

---

### View Modes

Once the pipeline has run, toggle between these representations using the tabs in the analysis panel:

| Mode | Description |
|---|---|
| **Deprojection** | Face-on deprojected image (sky-aligned, North up) from the current geometry. |
| **Model** | The azimuthally-averaged synthetic model — a perfectly symmetric reconstruction of the disk. |
| **Residuals** | Difference between the deprojected image and the model. Highlights non-axisymmetric structures such as spirals, arcs, or clumps. |
| **Polar** | The deprojected image resampled into polar coordinates (Radius vs. Azimuth angle). |

---

### Analysis Tools

**Auto-Tune Geometry**
Refines inclination, position angle, and center with a coarse inclination/PA grid plus local **L-BFGS-B** minimization of the geometric loss (`POST /optimize_geometry`). Treat the result as an approximate suggestion: it can miss the true geometry (local minima, PA degeneracy at low *i*, noisy or asymmetric disks). Always verify against the ellipse overlay. This is **not** the CLI hybrid (CNN prior + differential evolution + L-BFGS-B).

**Gaussian Ring Fitting**
Click and drag on the radial profile chart to define a fitting range. The pipeline fits a Gaussian to the selected interval and reports:
- **Peak Radius** — centroid of the fitted Gaussian in arcsec.
- **Width (FWHM)** — full width at half maximum of the ring in arcsec.

**Cursor Probe (Inspector)**
While the Inspector tool is active, hovering over the image shows:
- **Radius** — radial position in arcseconds.
- **Intensity** — brightness temperature at the nearest profile sample, in Kelvin.

**Custom Markers**
Click **Add Marker** to enter placement mode. A dialog lets you define a label, shape (`circle`, `square`, `star`, `cross`), and color. Markers are rendered as overlays on the image for the duration of the session.

**SIMBAD Query**
Click the **SIMBAD** button in the metadata panel to query the CDS database for known objects near the image center (within 2 arcminutes). Returns object type, V-band magnitude, and distance.

**Real-Time Charts**
- **Radial Profile** — Intensity vs. Radius with toggleable linear / logarithmic Y-axis scaling.
- **Cumulative Flux** — Enclosed flux fraction as a function of radius.

---

### Display Configuration

Click **Settings** in the analysis panel toolbar to access visualization controls:

| Control | Options |
|---|---|
| **Colormap** | `magma`, `inferno`, `viridis`, `seismic`, `gray`, `jet` (all invertible) |
| **Stretch** | `asinh`, `linear`, `log`, `sqrt` |
| **Intensity Limits** | Manual `Vmin` / `Vmax`, or **Auto** (percentile-based scaling) |
| **Contours** | Off, or percentiles / N evenly spaced levels (same options as the Matplotlib Widget) |
| **Overlays** | Axes, colorbar, contours (beam overlay in the Matplotlib Widget) |
| **Default stretch** | `linear` |

---

### Export & Session Management

| Action | Description |
|---|---|
| **Download FITS** | Saves the currently displayed view (Deprojection, Model, Residuals, or Polar) as a standard `.fits` file. |
| **CSV Export** | Downloads the 1D radial profile — Radius, Raw Intensity, and Brightness Temperature — as `radial_profile.csv`. |
| **Matplotlib Widget** | Opens a secondary panel with a high-DPI Matplotlib figure and configurable axes, colorbar, and beam overlay. |
| **Save Session** | Serializes `{filename, params, pixelScale, timestamp}` to a downloadable `.json` file. |
| **Restore Session** | Load a saved `.json` via the folder icon to resume with all parameters restored. |

---

## CLI Pipeline

The CLI pipeline is designed for automated, reproducible processing without any browser interaction. It discovers FITS files in the working directory, groups them by source name and spectral band, and processes each group through five sequential phases: FITS reading → geometry optimization → beam homogenization → deprojection & profile extraction → output writing.

DiscoNet weights are loaded once at startup and reused across all groups. If the model file is absent, the pipeline falls back to analytical geometry optimization.

### Usage Examples

```bash
# Process ALL FITS files found in the current working directory
disco-start

# Process a single object by name prefix
disco-start AS209

# Process multiple objects in one run
disco-start AS209 Elias29 DoAr25

# Process a directory group
disco-start path/to/group/

# Process a FITS file directly
disco-start path/to/disk.fits

# Force inclination and PA, export CSV and debug image
disco-start AS209 --incl 35.0 --pa 120.0 --csv on --debug on

# Set outer radius and disable beam homogenization
disco-start AS209 --rout 1.2 --homobeam off

# Specify a custom homogenization beam size
disco-start AS209 Elias29 --homobeam on --beam 0.15

# Skip the interactive confirmation prompt (scripts / non-interactive)
disco-start AS209 --yes
disco-start path/to/disk.fits -y
```

> If no `identifier` is provided, DISCO discovers and processes **all** FITS files found in the current directory tree.

Before scanning, the CLI prints a warning with the current working directory and asks `Are you sure you want to continue? [y/N]`. Pass `-y` / `--yes` to skip the prompt (required in non-interactive sessions).

### CLI Reference

```
usage: disco-start [-h] [--rout ROUT] [--rmin RMIN] [--incl INCL] [--pa PA]
                   [--beam BEAM] [--homobeam {on,off}] [--csv {on,off}]
                   [--debug {on,off}] [-y] [identifier ...]
```

| Argument | Default | Description |
|---|---|---|
| `identifier` | *(all FITS in CWD)* | Object name prefix(es), directory path(s), or direct `.fits` file path(s). |
| `--rout ROUT` | auto | Force outer radius in arcsec. Bypasses automatic estimation. |
| `--rmin RMIN` | `0.0` (auto) | Force inner radius / cavity in arcsec. When `0.0`, auto-detected from beam size. |
| `--incl INCL` | auto | Force disk inclination in degrees. Must be paired with `--pa` to skip the optimization phase entirely. |
| `--pa PA` | auto | Force position angle in degrees. Must be paired with `--incl` to skip the optimization phase entirely. |
| `--beam BEAM` | auto | Target beam size in arcsec for homogenization. Defaults to the largest beam in the group × 1.01. |
| `--homobeam {on,off}` | `on` | Enable / disable beam homogenization. **Enabled by default.** |
| `--csv {on,off}` | `off` | Write CSV outputs: global parameters, per-band metadata, and tabulated radial profiles. |
| `--debug {on,off}` | `off` | Save a diagnostic PNG overlaying the optimized center and outer radius on the deprojected image. |
| `-y`, `--yes` | off | Skip the interactive confirmation prompt before FITS scanning. |

---

## Tech Stack

| Layer | Technology |
|---|---|
| Backend | Python 3.9+, FastAPI, Uvicorn |
| Science | Astropy, SciPy, NumPy, astroquery |
| Deep Learning | PyTorch (DiscoNet CNN) |
| Frontend | React, Vite, BlueprintJS, Recharts |
| Distribution | PyPI (`disco-astronomy`) |

---

## License

This project is licensed under the [MIT License](https://opensource.org/licenses/MIT).

---

## Support & Contact

If you encounter issues or have questions, feel free to reach out:

📬 **jorge.guzman.l@usach.cl**

Bug reports and feature requests are welcome via [GitHub Issues](https://github.com/astrojorgeluis/disco-astronomy).
