uvex_transients.simulation.event_catalog.EventCatalog.compute_yield_summary#

EventCatalog.compute_yield_summary(detected: EventCatalog, exposure: ExposureCatalog, transients: dict[str, ExtragalacticTransient], confidence: float = 0.9) → YieldTable[source]#

Build a per-transient-type yield summary, combining this catalog, detected, and exposure.

One row per transient type in transients, with:

  • total_exposure/total_exposure_fraction: ~uvex_transients.simulation.exposure_catalog.ExposureCatalog.total_effective_exposure/ ~uvex_transients.simulation.exposure_catalog.ExposureCatalog.coverage_fraction.

  • integrated_rate: ~uvex_transients.transients.base.ExtragalacticTransient.integrated_rate (the per-steradian, per-year rate integrated over redshift).

  • all_sky_rate: that same rate restored to the full \(4\pi\) sky (~uvex_transients.transients.base.ExtragalacticTransient.all_sky_rate), with no survey footprint applied.

  • uvex_intrinsic_rate/uvex_intrinsic_events: the footprint-aware analogues of the previous two, derived from exposure rather than the full sky – uvex_intrinsic_events is exactly ~uvex_transients.simulation.exposure_catalog.ExposureCatalog.total_expected_events (\(\mu_0\) in Yield Statistics), and uvex_intrinsic_rate is that same count divided by ~uvex_transients.simulation.exposure_catalog.ExposureCatalog.total_duration.

  • detected_events: \(k\), from compute_detection_efficiency.

  • detection_probability: \(\hat\epsilon=k/n\) (compute_detection_efficiency).

  • expected_detections: \(\hat\lambda=\mu_0\hat\epsilon\), Yield Statistics’s boxed yield estimator.

Every rate-derived quantity (integrated_rate, all_sky_rate, uvex_intrinsic_rate, uvex_intrinsic_events) carries the rate-only bounds implied by each transient’s own RATE_CI as ..._lower/..._upper columns – these collapse to the point estimate when RATE_CI is unset, exactly like ~uvex_transients.transients.base.ExtragalacticTransient.rate_ci itself.

detection_probability and expected_detections each carry two separate two-sided intervals rather than one combined box (Yield Statistics’s “simulation-only” vs. “rate-only” bounds, kept apart so either source of uncertainty stays inspectable on its own): ..._binom_lower/..._binom_upper (Clopper-Pearson, propagated through \(\hat\lambda=\mu_0\hat\epsilon\) for expected_detections) and ..._rate_lower/ ..._rate_upper (RATE_CI, holding \(\hat\epsilon\) fixed). detection_probability itself doesn’t depend on the rate normalization at all – it’s a ratio of Monte Carlo counts – so its ..._rate_lower/..._rate_upper columns always equal its own point estimate; they’re included only so every row shares one column schema.

Parameters:

  • detected (EventCatalog) – Forwarded to compute_detection_efficiency.

  • exposure (ExposureCatalog) – Supplies every footprint-aware quantity above; see the column list.

  • transients (dict[str, ExtragalacticTransient]) – Transient-type instances, keyed the same way as self.transient_type and exposure.transient_type. One output row per key, sorted by name.

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

Returns:

One row per transient type, sorted by name; see the column list above.

Return type:

YieldTable

Raises:

KeyError – If exposure has no tabulated exposure for a type named in transients.