sagui
Photometric SED-based segmentation for IFU data cubes.
Install Quick Start GitHub
Part of the COIN Toolbox

What It Does

sagui combines photometric preprocessing and region-based SED extraction in one workflow:

  • build a white-light representation of an IFU cube
  • derive a starlet-based photometric mask
  • optionally pretransform the valid spectra before clustering
  • cluster valid spaxels into regions
  • extract integrated SEDs and propagated uncertainties
  • project region properties back onto the image plane

Core Ideas

Photometric Masking

Collapse the cube, reconstruct selected starlet scales, and isolate spatially meaningful regions before clustering.

Region Segmentation

Segment only the valid spaxels, keeping the clustering logic aligned with the original capivara workflow while allowing benchmarkable spectral pretransforms.

Integrated Region SEDs

Summarize each region as an integrated SED with uncertainty propagation rather than a representative median spectrum.

Quick Start

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

x <- FITSio::readFITS("manga-8135-12701-LOGCUBE.fits")

seg <- segment_regions(
  input = x,
  Ncomp = 30,
  use_starlet_mask = TRUE,
  starlet_J = 5,
  starlet_scales = 2:5,
  pretransform = "asinh"
)

plot_region_map(seg, palette = "magma")

Installation

Install from GitHub:

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

For the faster clustering backend:

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

Region SEDs

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

head(sed$flux_long)

Clustering Pretransforms

You can benchmark simple transforms against copula-based mappings without changing the rest of the segmentation workflow:

seg_asinh <- segment_regions(x, Ncomp = 30, pretransform = "asinh")
seg_copula <- segment_regions(x, Ncomp = 30, pretransform = "copula_gaussian")

Region Property Maps

plot_region_property_map(
  seg,
  values = setNames(sed$flux_wide$n_pix, sed$flux_wide$region),
  value_label = "Pixels per region"
)

Why sagui

The package is designed for cases where the final object of interest is a region-integrated SED with uncertainty, not just a segmented image or a representative median spectrum.

  • clustering operates on scaled per-spaxel vectors
  • region summaries are integrated over the segmented regions
  • output is suitable for downstream SED fitting and region-based analysis

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.