Segmentation Backends

Capivara exposes an exact Ward backend and a sparse-graph Ward backend. They return compatible region maps and regional-product inputs, but they make different computational approximations.

Exact Ward

segment() constructs the full pairwise distance object among valid spaxels. The distance storage therefore grows quadratically with the number of eligible spaxels. Estimate the lower-bound memory before a large run:

estimate_segment_memory(cube)

seg <- segment(
  input = cube,
  Ncomp = 25,
  use_starlet_mask = TRUE
)

Use the exact backend when its all-pairs distance matrix fits in memory.

Sparse Ward

segment_large() avoids storing the full all-pairs distance matrix by building a coherent nearest-neighbour graph.

seg <- segment_large(
  input = cube,
  Ncomp = 25,
  use_starlet_mask = TRUE,
  knn_k = 100,
  auto_k = FALSE,
  verbose = TRUE
)

seg$backend_info

knn_k controls graph density. With auto_k = TRUE, Capivara may increase it to connect the graph; the value used is returned in backend_info.

Select spectral channels

By default, all wavelength channels drive the segmentation. Set feature_wavelength_range to learn labels from a chosen interval while keeping the full cube in the returned object:

seg_window <- segment_large(
  input = cube,
  Ncomp = 25,
  feature_wavelength_range = c(lambda_min, lambda_max),
  use_starlet_mask = TRUE,
  knn_k = 100
)

full_regional_spectra <- summarize_cluster_spectra(seg_window)$sum_spectra

feature_wavelength_range selects the clustering channels. wavelength_range selects the channels used by the S/N screen. The two parameters are not aliases.

Choose the component count

choose_ncomp_by_snr() evaluates candidate cuts and returns the largest tested count whose minimum regional S/N remains above the requested threshold.

choice <- choose_ncomp_by_snr(
  input = cube,
  target_snr = 30,
  var_cube = variance_cube,
  k_values = c(5, 10, 15, 20),
  wavelength_range = c(lambda_min, lambda_max)
)

The result depends on the target, variance cube, candidate grid, and wavelength interval.