Photometric SED segmentation for astronomical cubes
sagui
Segment broadband or medium-band image cubes into regions with similar photometric SEDs, then export flux-conserving regional photometry for downstream SED fitting.
Quick start Paper cases Python handoff GitHub
Sagui-10 segmentation example
Part of the COIN Toolbox

What sagui does

sagui is built for analyses where the segmentation is not the final product. The final product is usually a table of region-integrated SEDs that can be sent to an SED-fitting code.

Segmentation mosaic from the manuscript: several galaxies segmented with the same SAGUI workflow.

1. Build a support mask

Collapse the cube into a white image, decompose it with starlets, and keep the scales that trace coherent galaxy structure.

2. Cluster pixel SEDs

Cluster valid pixels using Ward-style hierarchical clustering. Use the exact backend for compact cubes and sparse Ward for larger cubes.

3. Export regional SEDs

Sum the flux density over all pixels in each region. The summed regional SED is the flux-conserving product used for SED fitting.

Installation

install.packages("remotes")
remotes::install_github("RafaelSdeSouza/sagui")
library(sagui)

Optional acceleration packages:

install.packages("fastcluster")
install.packages("torch")

Quick start

suppressPackageStartupMessages({
  library(sagui)
  library(FITSio)
})

cube <- FITSio::readFITS("my_psfmatched_cube.fits")

seg <- segment_regions(
  input = cube,
  Ncomp = 20,
  use_starlet_mask = TRUE,
  starlet_J = 5,
  starlet_scales = 2:5,
  cluster_pretransform = "none"
)

plot_region_map(seg, palette = c("#213E60", "#94B6EF", "#F4F2EF", "#E68C3A"))

The output is a labeled image-plane segmentation:

Example 20-region SAGUI segmentation for Sagui-10.

Extract the flux-conserving SED table:

sed <- extract_region_sed(
  cube = cube,
  labels = seg$cluster_map,
  band_values = FITSio::axVec(3, cube$axDat),
  error_fallback = "mad_sky"
)

head(sed$flux_long)

The flux column is the summed regional flux density. The table also includes flux_err, n_eff, n_pix, and the band wavelength when available.

Mnuscript examples

The manuscript focuses on the method and mathematical choices. Code examples are kept online so they can stay synchronized with the package interface.

Sagui-10

Sagui-10 20-region segmentation.

Run the 20-region segmentation used in the main figures, then export the segmentation map and summed regional SEDs.

Open example

Sagui-11 faint merger bridge

Sagui-11 low-surface-brightness merger composite from the manuscript.

The merger case from the low-surface-brightness section. Compare the ordinary run with a copula-transformed run for the faint bridge and outskirts.

Open example

Target S/N selection

Prospector-derived star-formation surface-density map painted back onto the segmentation.

Use choose_ncomp_by_snr(min_snr = ...) to select the finest segmentation that still satisfies a minimum regional S/N. The candidate Ncomp values are only the discrete search space used by the wrapper.

Open example

Python handoff

Example 20-region SAGUI segmentation for Sagui-10.

Save regional SEDs as CSV and the label map as FITS, then read the products with pandas and astropy.

Open example

Exact and sparse runs

Use segment_regions() when the full pairwise distance matrix fits in memory. Use segment_regions_large() when the number of valid pixels is large.

seg_large <- segment_regions_large(
  input = cube,
  Ncomp = 40,
  use_starlet_mask = TRUE,
  starlet_J = 5,
  starlet_scales = 2:5,
  cluster_pretransform = "copula_gaussian",
  knn_k = 100,
  spatial_weight = 0.02
)

The sparse backend keeps the same output structure: cluster_map, mask products, metadata, and compatibility with extract_region_sed().

Design choices

  • sagui clusters pixel SED shapes inside a foreground support mask.
  • Region photometry is summed, not averaged, by default.
  • Mean SEDs are useful diagnostics, but summed fluxes are the SED-fitting input.
  • Mask construction and clustering pretransforms are separate controls.
  • The package keeps manuscript examples online to avoid freezing fragile syntax into the paper body.

References

  1. Bundy, Kevin, et al. (2015). Overview of the SDSS-IV MaNGA Survey: Mapping Nearby Galaxies at Apache Point Observatory. The Astrophysical Journal, 798(1), 7. https://doi.org/10.1088/0004-637X/798/1/7
  2. de Souza, R. S., et al. (2025). CAPIVARA: A spectral-based segmentation method for IFU data cubes. Monthly Notices of the Royal Astronomical Society, 539(4), 3166-3179. https://doi.org/10.1093/mnras/staf688
  3. Starck, J.-L., Murtagh, F., and Fadili, J. (2015). Sparse Image and Signal Processing: Wavelets, Curvelets, Morphological Diversity. Cambridge University Press.