Choose the Number of Clusters from a Target SNR Cut — choose_ncomp_by

This function computes the Capivara dendrogram once, evaluates a grid of cuts, and chooses the largest number of clusters whose minimum bin SNR remains above the requested threshold.

Usage

choose_ncomp_by_snr(
  input,
  target_snr,
  var_cube = NULL,
  k_values = NULL,
  wavelength_range = NULL,
  redshift = 0,
  scale_fn = median_scale,
  snr_stat = c("integrated", "median_per_wavelength"),
  variance_inflation = 1,
  na_safe = TRUE
)

Arguments

input: A FITS-like object with an imDat cube, or a raw 3-D array.
target_snr: Minimum accepted SNR per cluster.
var_cube: Optional variance cube matching the flux cube dimensions. When omitted, a simple Poisson-like approximation var = pmax(flux, 0) is used.
k_values: Optional integer vector of candidate cluster counts. By default, all valid counts are tested from the maximum down to 1.
wavelength_range: Optional numeric vector of length 2 selecting the wavelength interval used to compute SNR.
redshift: Numeric redshift placeholder kept for API compatibility.
scale_fn: Row-wise scaling function used during segmentation.
snr_stat: Either integrated SNR across the chosen window or the median per-wavelength SNR inside that window.
variance_inflation: Multiplicative factor applied to propagated variances.
na_safe: Logical; when TRUE, use the missing-data-safe scaling path.

Value

A segmentation result with the chosen Ncomp, the per-cluster SNRs at the selected cut, and a table showing the SNR screen across tested values of k.