uvex_transients.surveys.base.SurveySchedule.compute_control_time#

SurveySchedule.compute_control_time(timescale: Quantity, minimum_factor: float | None = None, maximum_factor: float | None = None, visibility_factor: float | None = None, start_time: Time | None = None, end_time: Time | None = None, nside: int | None = None, order: str | None = None) → tuple[Quantity, Quantity][source]#

Compute transient control time as a function of sky position.

For each HEALPix pixel, the control time is the total duration over which a transient with characteristic timescale timescale could begin and still receive useful temporal sampling from the survey: at least one pair of observations separated by

minimum_factor * timescale <= dt <= maximum_factor * timescale,

with the later observation occurring within visibility_factor * timescale of transient onset. Overlapping intervals of allowed start times are merged before summing, so no candidate start time is counted twice.

This is the statistic to reach for when you need to know not just whether a pixel can ever catch a timescale-T transient (see compute_pair_counts(), which only answers that existence question), but for how much of the survey it remains able to – important once a pixel is revisited many times (e.g. across repeated full-sky passes), since a pixel hit by one lucky pair and a pixel with continuous cadence support look identical under an existence-only statistic but very different here.

Built on compute_visit_times() and _pixel_control_time(), both the per-visit interval construction and the interval merge are fully vectorized (no Python-level loop over visits), so cost stays O(n log n) per pixel rather than the O(n) sequential Python loop the original implementation of this statistic used.

Parameters:

  • timescale (Quantity) – Characteristic transient timescale.

  • minimum_factor (float, optional) – Minimum useful observation separation relative to timescale, or None (the default) to use config["surveys.cadence.minimum_factor"].

  • maximum_factor (float, optional) – Maximum useful observation separation relative to timescale, or None (the default) to use config["surveys.cadence.maximum_factor"].

  • visibility_factor (float, optional) – Duration over which the transient is assumed useful for temporal characterization, relative to timescale, or None (the default) to use config["surveys.cadence.visibility_factor"].

  • start_time (Time, optional) – Optional survey interval over which to calculate control time.

  • end_time (Time, optional) – Optional survey interval over which to calculate control time.

  • nside (int, optional) – HEALPix resolution parameter, or None to use config["healpix.default_nside"].

  • order (str, optional) – HEALPix ordering scheme, either "nested" or "ring", or None to use config["healpix.default_order"].

Returns:

  • control_time (Quantity) – Full-sky HEALPix map of control times with shape (12 * nside**2,).

  • exposure (Quantity) – Survey-integrated area-time exposure,

    sum(control_time * pixel_area),

    with dimensions of solid angle times time.