uvex_transients.simulation.photometry_catalog.PhotometryCatalog.compute_detection_count_table#

PhotometryCatalog.compute_detection_count_table(event_catalog, exposure: ExposureCatalog, transients: dict[str, ExtragalacticTransient], snr_threshold: float, confidence: float = 0.9) → QTable[source]#

Per-transient-type estimator of how many events would show \(N_{\rm det}\ge k\) detected epochs.

A “detection” here is per-epoch, not per-band: an event’s row at a given obs_time counts as one detected epoch if any of its bands has snr > snr_threshold there – the same one-band-suffices convention ~uvex_transients.simulation.core.SurveySimulator.filter_by_snr uses to collapse bands before counting visits. Each event’s own count of detected epochs, \(N_{\rm det}\), is histogrammed within each transient type, exactly as ~uvex_transients.simulation.event_catalog.EventCatalog.compute_detection_efficiency histograms its own single k (its detected/undetected split is this table’s \(N_{\rm det}\ge 1\) row).

Every event in event_catalog is accounted for, including one with zero rows in this catalog at all (e.g. a survey never observed it) – it contributes \(N_{\rm det}=0\), so n_total always equals event_catalog’s own per-type row count, not just however many events happen to appear in this catalog’s table.

This is the full Yield Statistics treatment, one threshold \(k\) at a time, not just a raw Monte Carlo histogram: fraction \(=n_{\ge k}/n\) is ~uvex_transients.simulation.event_catalog.EventCatalog.compute_detection_efficiency’s own \(\hat\epsilon\), generalized from “detected at all” to “detected in \(\ge k\) epochs”, with the same Clopper-Pearson bounds (~uvex_transients.simulation._stats.clopper_pearson_interval). expected_events \(=\mu_0\hat\epsilon\) is ~uvex_transients.simulation.event_catalog.EventCatalog.compute_yield_summary’s own expected_detections estimator, generalized the same way – \(\mu_0\) (exposure’s ~uvex_transients.simulation.exposure_catalog.ExposureCatalog.total_expected_events) is the intrinsic, footprint-aware expected event count, independent of event_catalog’s own (possibly downsampled) size, so expected_events is a real expected number of UVEX events – not an artifact of how many Monte Carlo draws happened to be sampled or how heavily event_catalog was downsampled. Both expected_events uncertainty sources are kept separate exactly as compute_yield_summary keeps them: ..._binom_lower/_upper (Clopper-Pearson, propagated through \(\mu_0\hat\epsilon\)) and ..._rate_lower/ _upper (~uvex_transients.transients.base.ExtragalacticTransient.RATE_CI, holding \(\hat\epsilon\) fixed).

Parameters:

  • event_catalog (EventCatalog) – Supplies the full per-type event list this catalog’s photometry was computed over (via its own event_id/transient_type columns), so that events with zero qualifying epochs are still represented at \(N_{\rm det}=0\), and n_total/n for the Clopper-Pearson bounds.

  • exposure (ExposureCatalog) – Supplies \(\mu_0\), via ~uvex_transients.simulation.exposure_catalog.ExposureCatalog.total_expected_events.

  • transients (dict[str, ExtragalacticTransient]) – Transient-type instances, keyed the same way as event_catalog.transient_type and exposure.transient_type; supplies each type’s RATE_CI.

  • snr_threshold (float) – An epoch counts as detected if at least one band’s snr exceeds this value.

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

Returns:

One row per (transient_type, n_detections) pair present for that type (n_detections running 0..max for each type), with columns transient_type, n_detections (\(N_{\rm det}=k\)), n_events (number of that type’s events with exactly \(k\) detected epochs), n_total (that type’s total event count, repeated on every row), n_at_least (number of that type’s events with \(N_{\rm det}\ge k\), i.e. the reverse cumulative sum of n_events), fraction/fraction_lower/fraction_upper (\(\hat\epsilon\) and its Clopper-Pearson bounds), and expected_events/expected_events_binom_lower/ expected_events_binom_upper/expected_events_rate_lower/expected_events_rate_upper (\(\mu_0\hat\epsilon\) and its two uncertainty sources). n_at_least/fraction at n_detections == 1 reproduce ~uvex_transients.simulation.event_catalog.EventCatalog.compute_detection_efficiency’s own k/efficiency for the same snr_threshold and n_visits=1.

Return type:

astropy.table.QTable

Raises:

KeyError – If exposure has no tabulated exposure, or transients no instance, for a transient type present in event_catalog.