uvex_transients.utils.plotting#

Shared plotting infrastructure for uvex_transients.

Two layers live here:

  • General infrastructure (resolve_fig_axes, set_plot_style, get_default_cmap, get_cmap, get_band_color) that every plotting function in the package and docs gallery is expected to go through, so that figure size, style, and color choices come from one place – config["plotting.*"] – rather than being repeated (and drifting) at each call site.

  • Reusable generators for the plot shapes that recur throughout the docs gallery: a full-sky HEALPix map plus its pooled histogram (plot_healpix_map/plot_histogram, both driven by ~uvex_transients.surveys.base.SurveySchedule’s per-pixel diagnostics), a per-band light curve of theory curve + SNR-thresholded detections + upper limits (plot_band_light_curve, driven by ~uvex_transients.models.core.base.SpectralModel.simulate_photometry), and the “detection funnel” figures below.

A detection funnel shows how many events of a population survive each progressively more expensive screening stage (sampled -> magnitude-limited -> SNR-detected; see ~uvex_transients.simulation.core.SurveySimulator). Each stage count carries two independent sources of uncertainty that are otherwise easy to conflate into a single, misleadingly precise bar:

  • MC (statistical) uncertainty: every stage after the first is a binomial subsample of the raw Monte Carlo draws in the first (“sampled”) stage, so its uncertainty is exactly the same Clopper-Pearson interval ~uvex_transients.simulation.event_catalog.EventCatalog.compute_detection_efficiency and ~uvex_transients.simulation.event_catalog.EventCatalog.compute_yield_summary already use for detection efficiency, propagated back into count units.

  • Rate (systematic) uncertainty: the population’s overall normalization, from ~uvex_transients.transients.base.ExtragalacticTransient.RATE_CI. Because it is a pure multiplicative scale on the underlying rate, it applies identically to every stage’s point estimate – unlike the MC uncertainty, it does not shrink as later stages winnow the sample down.

compute_funnel_bounds computes both; plot_detection_funnel draws them, together with the bars themselves, as two visually distinct error layers on the same matplotlib.axes.Axes.

Functions

add_funnel_legend(ax[, loc])

Add legend entries explaining plot_detection_funnel's two uncertainty layers.

compute_funnel_bounds(stage_counts[, ...])

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

get_band_color(band)

Look up a photometric band's plotting color, from config["plotting.band_colors"].

get_cmap(cmap)

Resolve a colormap name (or an already-resolved colormap) to a ~matplotlib.colors.Colormap.

get_default_cmap()

Return the package's default colormap, config["plotting.default_cmap"].

plot_band_light_curve(ax, band, t_obs, phot, *)

Draw one photometric band's theory curve, SNR-detected points, and upper limits onto ax.

plot_detection_funnel(ax, x, counts, ...[, ...])

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

plot_healpix_map(values, *[, nside, order, ...])

Aitoff-projected scatter of a full-sky HEALPix map, log-color-scaled.

plot_histogram(values, *[, title, xlabel, ...])

Log-binned histogram of a strictly positive quantity, e.g. one pooled across a HEALPix map's pixels.

plot_rate_bars(ax, categories, ...)

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

resolve_fig_axes([fig, axes, fig_size, dpi, ...])

Resolve a (figure, axes) pair from any combination of already-provided pieces.

set_plot_style()

Apply the package's default matplotlib style, from config["plotting.*"].