uvex_transients.utils.plotting.plot_rate_bars#

uvex_transients.utils.plotting.plot_rate_bars(ax: ~matplotlib.axes._axes.Axes, categories: ~collections.abc.Sequence[str], visible_counts: ~collections.abc.Sequence[int], n_samples: int, all_sky_rate: ~astropy.units.quantity.Quantity, *, rate_ci: tuple[float, float] | None = None, confidence: float = 0.9, color: str | ~collections.abc.Sequence[str] | None = None, width: float = 0.6, rate_unit: ~astropy.units.core.Unit = <Quantity 1. 1 / yr>, label: str | None = None) → NDArray[float64][source]#

Bar chart of an all-sky rate estimate per category (e.g. band), with MC + rate uncertainty.

Each category’s rate is estimated as the fraction of n_samples Monte Carlo draws that satisfy some visibility criterion (e.g. “peak apparent magnitude below the survey’s limit”), scaled by the population’s all_sky_rate. That is exactly compute_funnel_bounds’s “sampled -> screened” convention with n_samples playing the role of its shared binomial denominator, so the same two uncertainty layers plot_detection_funnel draws for a detection funnel apply here too: MC (statistical) uncertainty from treating each category’s count as a Clopper-Pearson binomial subsample of n_samples, and rate (systematic) uncertainty from rate_ci (see ~uvex_transients.transients.base.ExtragalacticTransient.RATE_CI), which scales every category’s point estimate by the same factor rather than shrinking with the sample.

Parameters:

ax (matplotlib.axes.Axes) – Axes to draw onto.
categories (sequence of str) – Bar labels, e.g. band names.
visible_counts (sequence of int) – Number of the n_samples draws satisfying each category’s visibility criterion, e.g. np.count_nonzero(peak_mag < limit) per band.
n_samples (int) – Total Monte Carlo draws each visible_counts entry is a subsample of.
all_sky_rate (astropy.units.Quantity) – The population’s all-sky rate (~uvex_transients.transients.base.ExtragalacticTransient.all_sky_rate); each bar height is visible_counts[i] / n_samples * all_sky_rate.
rate_ci (tuple of float, optional) – (lower, upper) multiplicative rate bounds; see compute_funnel_bounds. None (the default) omits the rate (systematic) uncertainty band.
confidence (float, optional) – Confidence level for the MC (statistical) uncertainty. The default is 0.9.
color (str or sequence of str, optional) – Forwarded to plot_detection_funnel.
width (float, optional) – Bar width. The default is 0.6.
rate_unit (astropy.units.Unit, optional) – Unit the bars (and the returned array) are expressed in. The default is 1 / u.yr.
label (str, optional) – Legend label for the bars themselves.

Returns:

The plotted bar heights (visible rates), in rate_unit.

Return type:

numpy.ndarray