uvex_transients.utils.plotting.compute_funnel_bounds#

uvex_transients.utils.plotting.compute_funnel_bounds(stage_counts: Sequence[int], rate_ci: tuple[float, float] | None = None, confidence: float = 0.9) → tuple[NDArray[float64], NDArray[float64], NDArray[float64], NDArray[float64]][source]#

Compute per-stage MC and rate bounds for a detection-funnel’s raw (undownsampled) counts.

stage_counts[0] is taken as the funnel’s binomial denominator \(n\) – the number of raw Monte Carlo draws in the “sampled” stage – and every later stage’s count \(k_i\) is treated as a binomial subsample of it, with a clopper_pearson_interval bound on \(k_i/n\) converted back into count units. This matches ~uvex_transients.simulation.event_catalog.EventCatalog.compute_yield_summary’s own convention (feasible draws as \(n\), a later cut’s count as \(k\)), just applied to every stage rather than only the final one.

rate_ci (an ~uvex_transients.transients.base.ExtragalacticTransient.RATE_CI-style (lower, upper) multiplicative pair, or None) is applied uniformly to every stage’s point estimate, since it rescales the population’s overall rate normalization rather than any stage’s selection efficiency.

Parameters:

  • stage_counts (sequence of int) – Raw (undownsampled) event counts at each funnel stage, in order, e.g. (len(catalog), len(mag_filtered), len(detected)). Each entry must not exceed stage_counts[0].

  • rate_ci (tuple of float, optional) – (lower, upper) multiplicative bounds, as ExtragalacticTransient.RATE_CI. None (the default) collapses the rate bounds to the point estimate, i.e. (1.0, 1.0).

  • confidence (float, optional) – Confidence level for the Clopper-Pearson MC bounds. The default is 0.9.

Returns:

  • mc_lower (numpy.ndarray) – Per-stage Clopper-Pearson lower bound, in the same (undownsampled) count units.

  • mc_upper (numpy.ndarray) – Per-stage Clopper-Pearson upper bound, in the same (undownsampled) count units.

  • rate_lower (numpy.ndarray) – Per-stage rate-normalization lower bound, in the same (undownsampled) count units.

  • rate_upper (numpy.ndarray) – Per-stage rate-normalization upper bound, in the same (undownsampled) count units.

Notes

To plot alongside a downsample-rescaled counts array, multiply all four returned arrays by the same downsample factor first.