uvex_transients.utils.plotting.plot_detection_funnel#

uvex_transients.utils.plotting.plot_detection_funnel(ax: Axes, x: NDArray[float64], counts: NDArray[float64], mc_lower: NDArray[float64], mc_upper: NDArray[float64], rate_lower: NDArray[float64], rate_upper: NDArray[float64], color: str | Sequence[str] | None = None, width: float = 0.8, label: str | None = None) → None[source]#

Draw one funnel’s bars plus its MC and rate uncertainty layers onto ax.

The two uncertainty sources are drawn as visually distinct layers rather than combined into one interval, since they behave differently (MC uncertainty narrows at later stages as the binomial denominator’s share grows more certain; rate uncertainty is a constant fractional band on every stage) and conflating them would hide that:

  • Rate (systematic) uncertainty is drawn first, as a wide, pale-filled rectangle in color spanning the full bar width from rate_lower to rate_upper, outlined with an opaque edge in the same color – a shaded envelope rather than an error bar, since it applies uniformly to every stage and reads more like a systematic “this whole bar could be scaled by …” than a per-point measurement uncertainty. The opaque outline keeps both endpoints – including the lower bound, which a capless translucent line alone tends to fade into the axes background – legible at a glance.

  • MC (statistical) uncertainty is drawn on top, as a narrow black error bar with caps – the conventional per-point measurement-uncertainty treatment, layered over the systematic band so both remain legible at once.

Parameters:

  • ax (matplotlib.axes.Axes) – Axes to draw onto.

  • x (numpy.ndarray) – Bar center positions, one per stage.

  • counts (numpy.ndarray) – Bar heights (downsample-rescaled stage counts), one per stage.

  • mc_lower (numpy.ndarray) – Bound arrays from compute_funnel_bounds, rescaled by the same downsample factor as counts.

  • mc_upper (numpy.ndarray) – Bound arrays from compute_funnel_bounds, rescaled by the same downsample factor as counts.

  • rate_lower (numpy.ndarray) – Bound arrays from compute_funnel_bounds, rescaled by the same downsample factor as counts.

  • rate_upper (numpy.ndarray) – Bound arrays from compute_funnel_bounds, rescaled by the same downsample factor as counts.

  • color (str or sequence of str, optional) – Bar (and rate-band) color: either one color shared by every bar, or one color per bar (e.g. one per funnel stage, or one per transient type in a grouped funnel), matched positionally against x. Defaults to config["plotting.funnel_color"].

  • width (float, optional) – Bar width, forwarded to ~matplotlib.axes.Axes.bar. The default is 0.8.

  • label (str, optional) – Legend label for the bars.