wcc-sim 0.1.0__py3-none-any.whl

wcc_phot/__init__.py

@@ -0,0 +1,6 @@
+__version__ = "0.1.0"
+
+from .geometry import PhotGeometry  # noqa: E402,F401
+from .live import LiveViewer  # noqa: E402,F401
+from .pipeline import PhotometryResult, run_photometry  # noqa: E402,F401
+from .report import make_report  # noqa: E402,F401

wcc_phot/apphot.py

@@ -0,0 +1,69 @@
+"""Aperture photometry with CCD-equation errors from the frame header rates."""
+
+import numpy as np
+from astropy.stats import SigmaClip
+from photutils.aperture import ApertureStats, CircularAnnulus, CircularAperture
+
+from .flags import FLAG_EDGE, FLAG_SATURATED
+
+
+def _saturated_within(satmask, x, y, radius):
+    """True if any saturated pixel lies within `radius` px of (x, y)."""
+    ny, nx = satmask.shape
+    r = int(np.ceil(radius))
+    x0, y0 = int(round(x)), int(round(y))
+    y_lo, y_hi = max(y0 - r, 0), min(y0 + r + 1, ny)
+    x_lo, x_hi = max(x0 - r, 0), min(x0 + r + 1, nx)
+    if y_lo >= y_hi or x_lo >= x_hi:
+        return False
+    return bool(satmask[y_lo:y_hi, x_lo:x_hi].any())
+
+
+def aperture_photometry_frame(frame, x, y, geom):
+    """Background-subtracted aperture fluxes at (x, y) on the electron image.
+
+    Returns (flux_e, flux_err_e, bkg_e_pix, flags). Background is the
+    sigma-clipped annulus median; the variance is Poisson of the star plus
+    the per-pixel background variance from the header rates
+    ((sky+dark)*exptime + n_reads*read_noise^2), including the
+    background-estimate term (area^2/n_annulus).
+    """
+    x = np.atleast_1d(np.asarray(x, dtype=float))
+    y = np.atleast_1d(np.asarray(y, dtype=float))
+    positions = np.column_stack([x, y])
+    aper = CircularAperture(positions, r=geom.r_ap)
+    annulus = CircularAnnulus(positions, r_in=geom.r_in, r_out=geom.r_out)
+
+    bkg = np.asarray(
+        ApertureStats(
+            frame.image_e, annulus, sigma_clip=SigmaClip(sigma=3.0)
+        ).median,
+        dtype=float,
+    )
+    raw = np.asarray(ApertureStats(frame.image_e, aper).sum, dtype=float)
+    area = aper.area
+    flux = raw - bkg * area
+
+    m = frame.meta
+    var_pix = (
+        (float(m["sky_e_s"]) + float(m["dark_e_s"])) * float(m["exptime"])
+        + int(m["n_reads"]) * float(m["read_noise"]) ** 2
+    )
+    variance = np.clip(flux, 0, None) + area * var_pix * (
+        1.0 + area / annulus.area
+    )
+    flux_err = np.sqrt(variance)
+
+    ny, nx = frame.image_e.shape
+    flags = np.zeros(x.size, dtype=int)
+    edge = (
+        (x < geom.r_out)
+        | (x > nx - 1 - geom.r_out)
+        | (y < geom.r_out)
+        | (y > ny - 1 - geom.r_out)
+    )
+    flags[edge] |= FLAG_EDGE
+    for i in range(x.size):
+        if _saturated_within(frame.satmask, x[i], y[i], geom.r_ap):
+            flags[i] |= FLAG_SATURATED
+    return flux, flux_err, bkg, flags

wcc_phot/centroid.py

@@ -0,0 +1,41 @@
+"""Per-frame re-centroiding of WCS-predicted star positions.
+
+Center-of-mass (not a Gaussian fit) because the +1/+2-wave defocus PSFs are
+centrally-depressed donuts; COM in a box sized to the PSF works for both.
+"""
+
+import warnings
+
+import numpy as np
+from photutils.centroids import centroid_com, centroid_sources
+
+from .flags import FLAG_CENTROID
+
+
+def centroid_stars(frame, x0, y0, box):
+    """Refine (x0, y0) with a background-subtracted COM in a `box` px window.
+
+    Returns (x, y, flags); a failed or runaway centroid (>box px from the
+    start) falls back to the input position with FLAG_CENTROID set.
+    """
+    x0 = np.atleast_1d(np.asarray(x0, dtype=float))
+    y0 = np.atleast_1d(np.asarray(y0, dtype=float))
+    data = frame.image_e - np.median(frame.image_e)
+    ny, nx = data.shape
+    x_start = np.clip(x0, 0, nx - 1)
+    y_start = np.clip(y0, 0, ny - 1)
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")  # partial-overlap warnings at edges
+        x, y = centroid_sources(
+            data, x_start, y_start, box_size=box, centroid_func=centroid_com
+        )
+    flags = np.zeros(x0.size, dtype=int)
+    bad = (
+        ~np.isfinite(x)
+        | ~np.isfinite(y)
+        | (np.hypot(x - x_start, y - y_start) > box)
+    )
+    flags[bad] |= FLAG_CENTROID
+    x[bad] = x0[bad]
+    y[bad] = y0[bad]
+    return x, y, flags

wcc_phot/cli.py

@@ -0,0 +1,110 @@
+"""Command-line interface: wcc-phot frame1.fits frame2.fits ... -o phot.fits"""
+
+import argparse
+
+import numpy as np
+
+from .pipeline import run_photometry
+
+
+def build_parser():
+    p = argparse.ArgumentParser(
+        prog="wcc-phot",
+        description=(
+            "Differential aperture/PSF photometry of a target and its best "
+            "reference stars across a series of wcc-sim FITS frames."
+        ),
+    )
+    p.add_argument("frames", nargs="+", help="wcc-sim FITS frames (same field)")
+    tgt = p.add_argument_group("target (source id or coordinates)")
+    tgt.add_argument("--source-id", type=int, default=None,
+                     help="Gaia source_id of the target")
+    tgt.add_argument("--ra", type=float, default=None, help="target RA [deg]")
+    tgt.add_argument("--dec", type=float, default=None, help="target Dec [deg]")
+    p.add_argument("--method", choices=["aperture", "psf"], default="aperture")
+    p.add_argument("--n-ref", type=int, default=10,
+                   help="number of reference stars")
+    p.add_argument("--r-ap", type=float, default=None,
+                   help="aperture radius [px] (default: model-PSF EE radius)")
+    p.add_argument("--r-in", type=float, default=None,
+                   help="annulus inner radius [px] (default: 1.5 r_ap)")
+    p.add_argument("--r-out", type=float, default=None,
+                   help="annulus outer radius [px] (default: 2.5 r_ap)")
+    p.add_argument("--centroid-box", type=int, default=None,
+                   help="centroid box side [px, odd]")
+    p.add_argument("--fit-shape", type=int, default=None,
+                   help="PSF fit region side [px, odd]")
+    p.add_argument("--ee", type=float, default=0.95,
+                   help="encircled-energy fraction for the default r_ap")
+    p.add_argument("--iso-dmag", type=float, default=1.0,
+                   help="reject refs with a neighbor brighter than G+iso_dmag")
+    p.add_argument("--lc-csv", default=None,
+                   help="also write the light curve as ECSV")
+    p.add_argument("--report", default=None, metavar="PATH",
+                   help="write a one-page PDF + PNG diagnostic report "
+                        "(field + apertures, light curve, centroids, "
+                        "noise metrics)")
+    p.add_argument("--live", action="store_true",
+                   help="live matplotlib window: frame + apertures + light "
+                        "curve updated as each image is analyzed")
+    p.add_argument("--live-pause", type=float, default=0.2,
+                   help="seconds to pause on each frame in live mode")
+    p.add_argument("--live-zoom", type=int, default=None,
+                   help="crop the live image panel to +-N px around the target")
+    p.add_argument("-o", "--output", required=True,
+                   help="output FITS path (STARS/PHOT/LC)")
+    return p
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+    if args.source_id is not None:
+        target = args.source_id
+    elif args.ra is not None and args.dec is not None:
+        target = (args.ra, args.dec)
+    else:
+        build_parser().error("give --source-id or both --ra and --dec")
+
+    viewer = None
+    if args.live:
+        from .live import LiveViewer
+
+        viewer = LiveViewer(pause=args.live_pause, zoom=args.live_zoom)
+
+    result = run_photometry(
+        args.frames,
+        target,
+        method=args.method,
+        n_ref=args.n_ref,
+        r_ap=args.r_ap,
+        r_in=args.r_in,
+        r_out=args.r_out,
+        centroid_box=args.centroid_box,
+        fit_shape=args.fit_shape,
+        ee=args.ee,
+        iso_dmag=args.iso_dmag,
+        output=args.output,
+        on_frame=viewer,
+        report=args.report,
+    )
+    if args.lc_csv is not None:
+        result.lightcurve.write(args.lc_csv, format="ascii.ecsv", overwrite=True)
+
+    lc = result.lightcurve
+    rms_ppm = 1e6 * float(np.nanstd(lc["rel_flux_norm"]))
+    err_ppm = 1e6 * float(np.nanmedian(lc["rel_flux_norm_err"]))
+    print(
+        f"Wrote {args.output}: {result.params['n_frames']} frames, "
+        f"target {result.params['target_source_id']} "
+        f"(G={result.stars['gmag'][0]:.2f}), "
+        f"{result.params['n_ref']} refs, {args.method} r_ap="
+        f"{result.params['r_ap']:.1f} px; rel-flux rms {rms_ppm:.0f} ppm "
+        f"(median error {err_ppm:.0f} ppm)"
+    )
+    if viewer is not None:
+        viewer.hold()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

wcc_phot/flags.py

@@ -0,0 +1,7 @@
+"""Per-measurement quality flag bits (bitwise OR-able)."""
+
+FLAG_CENTROID = 1  # centroid failed or ran away; WCS position used instead
+FLAG_SATURATED = 2  # saturated pixel within the aperture radius
+FLAG_EDGE = 4  # aperture/annulus clipped by the frame edge
+FLAG_FIT = 8  # PSF fit flagged by photutils or returned a non-finite flux
+FLAG_NOFLUX = 16  # relative flux undefined: non-finite target or ensemble <= 0

wcc_phot/geometry.py

@@ -0,0 +1,93 @@
+"""Aperture/centroid geometry, with defaults derived from the wcc-sim PSF model."""
+
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass
+class PhotGeometry:
+    """Pixel-space geometry shared by centroiding and photometry."""
+
+    r_ap: float  # aperture radius [px]
+    r_in: float  # background annulus inner radius [px]
+    r_out: float  # background annulus outer radius [px]
+    centroid_box: int  # COM centroid box side [px, odd]
+    fit_shape: int  # PSF-fit region side [px, odd]
+    ee_fraction: float | None = None  # model EE inside r_ap (None if user-set)
+
+
+def _odd(value):
+    n = int(np.ceil(value))
+    return n + 1 if n % 2 == 0 else n
+
+
+def geometry_from_r_ap(
+    r_ap,
+    r_in=None,
+    r_out=None,
+    centroid_box=None,
+    fit_shape=None,
+    ee_fraction=None,
+):
+    """PhotGeometry from an aperture radius; unset pieces get scaled defaults."""
+    r_ap = float(r_ap)
+    if r_ap <= 0:
+        raise ValueError(f"r_ap must be positive, got {r_ap}")
+    r_in = float(r_in) if r_in is not None else 1.5 * r_ap
+    r_out = float(r_out) if r_out is not None else 2.5 * r_ap
+    if not r_ap <= r_in < r_out:
+        raise ValueError(
+            f"need r_ap <= r_in < r_out, got {r_ap}, {r_in}, {r_out}"
+        )
+    centroid_box = (
+        int(centroid_box) if centroid_box is not None else _odd(2 * r_ap + 1)
+    )
+    fit_shape = int(fit_shape) if fit_shape is not None else _odd(2 * r_ap + 1)
+    if centroid_box % 2 == 0 or fit_shape % 2 == 0:
+        raise ValueError("centroid_box and fit_shape must be odd")
+    return PhotGeometry(r_ap, r_in, r_out, centroid_box, fit_shape, ee_fraction)
+
+
+def render_model_psf(meta, oversample=5):
+    """Oversampled model PSF for a frame's sensorfilter/focus/jitter."""
+    from wcc_sim.detectors import make_base_simulation
+    from wcc_sim.psf import render_oversampled_psf
+
+    sim = make_base_simulation(meta["sensorfilter"])
+    return render_oversampled_psf(
+        sim,
+        int(meta["focus"]),
+        oversample=oversample,
+        jitter_sigma_mas=float(meta["jitter_sigma_mas"]),
+    )
+
+
+def ee_radius(psf_det, fraction=0.95):
+    """Radius [px] enclosing `fraction` of a centered detector-sampled PSF."""
+    n = psf_det.shape[0]
+    center = (n - 1) / 2
+    yy, xx = np.mgrid[:n, :n]
+    r = np.hypot(xx - center, yy - center).ravel()
+    order = np.argsort(r)
+    cum = np.cumsum(psf_det.ravel()[order])
+    cum /= cum[-1]
+    i = int(np.searchsorted(cum, fraction))
+    return float(r[order][min(i, r.size - 1)])
+
+
+def default_geometry(meta, ee=0.95, oversample=5, psf_os=None):
+    """Model-PSF-driven geometry: r_ap = EE(ee) radius, annulus 1.5-2.5 r_ap."""
+    from wcc_sim.render import bin_oversampled
+
+    if psf_os is None:
+        psf_os = render_model_psf(meta, oversample=oversample)
+    psf_det = bin_oversampled(psf_os, oversample)
+    r_ap = float(np.ceil(max(ee_radius(psf_det, ee), 2.0)))
+
+    n = psf_det.shape[0]
+    center = (n - 1) / 2
+    yy, xx = np.mgrid[:n, :n]
+    inside = np.hypot(xx - center, yy - center) <= r_ap
+    ee_fraction = float(psf_det[inside].sum() / psf_det.sum())
+    return geometry_from_r_ap(r_ap, ee_fraction=ee_fraction)

wcc_phot/io.py

@@ -0,0 +1,110 @@
+"""Load WCC frames (wcc-sim FITS path, HDUList, or SimulatedField) for photometry."""
+
+import os
+import warnings
+from dataclasses import dataclass
+
+import numpy as np
+from astropy.io import fits
+from astropy.table import Table
+from astropy.wcs import WCS
+
+# meta key -> SCI header card (subset of wcc_sim.fitswriter._CARDS we need)
+_META_CARDS = {
+    "exptime": "EXPTIME",
+    "n_reads": "NREADS",
+    "gain": "GAIN",
+    "read_noise": "RDNOISE",
+    "sky_e_s": "SKYRATE",
+    "dark_e_s": "DARK",
+    "focus": "FOCUS",
+    "sensorfilter": "SENSORF",
+    "jitter_sigma_mas": "JITTER",
+    "plate_scale_mas": "PLTSCL",
+}
+
+
+@dataclass
+class Frame:
+    """One WCC exposure: delivered electron image + catalog + WCS + metadata.
+
+    ``image_e`` is the delivered product, ``(ADU - bias) * gain``, whether the
+    frame came from a SimulatedField's ``image_adu`` or a file's ``SCI``: the
+    ADC ceiling and the zero clip are in it on every path (issue #11).
+    """
+
+    image_e: np.ndarray  # [e-] (ADU - bias) * gain
+    satmask: np.ndarray  # bool
+    catalog: Table
+    wcs: WCS
+    meta: dict
+
+
+def _electrons(adu, meta):
+    """Delivered electrons: (ADU - bias) * gain, the one product photometry sees."""
+    return (np.asarray(adu, dtype=float) - meta["bias"]) * float(meta["gain"])
+
+
+def _meta_from_params(params):
+    meta = {key: params[key] for key in _META_CARDS}
+    meta["bias"] = float(params.get("bias", 0.0))
+    return meta
+
+
+def _meta_from_header(header):
+    try:
+        meta = {key: header[card] for key, card in _META_CARDS.items()}
+    except KeyError as err:
+        raise ValueError(
+            f"missing header card {err} — is this a wcc-sim FITS file?"
+        ) from None
+    meta["bias"] = float(header.get("BIAS", 0.0))  # files written before BIAS
+    return meta
+
+
+def load_frame(source):
+    """Build a Frame from a FITS path, an open HDUList, or a SimulatedField."""
+    if isinstance(source, Frame):
+        return source
+    if hasattr(source, "image_adu") and hasattr(source, "params"):
+        meta = _meta_from_params(source.params)
+        return Frame(
+            image_e=_electrons(source.image_adu, meta),
+            satmask=np.asarray(source.saturation_mask, dtype=bool),
+            catalog=source.catalog.copy(),
+            wcs=source.wcs,
+            meta=meta,
+        )
+    if isinstance(source, (str, os.PathLike)):
+        with fits.open(source) as hdul:
+            return _frame_from_hdulist(hdul)
+    return _frame_from_hdulist(source)
+
+
+def frame_meta(source):
+    """Read a frame's header metadata without loading the pixel data.
+
+    Same dispatch as load_frame (Frame / SimulatedField / FITS path /
+    HDUList) but for a path it reads only the SCI header, so a frame
+    series can be validated up front without holding every image in
+    memory. Returns the same meta dict load_frame builds.
+    """
+    if isinstance(source, Frame):
+        return source.meta
+    if hasattr(source, "image_adu") and hasattr(source, "params"):
+        return _meta_from_params(source.params)
+    if isinstance(source, (str, os.PathLike)):
+        return _meta_from_header(fits.getheader(source, "SCI"))
+    return _meta_from_header(source["SCI"].header)
+
+
+def _frame_from_hdulist(hdul):
+    header = hdul["SCI"].header
+    meta = _meta_from_header(header)
+    image_e = _electrons(hdul["SCI"].data, meta)
+    satmask = np.asarray(hdul["SATMASK"].data, dtype=bool)
+    catalog = Table(hdul["CAT"].data)
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")  # FITSFixedWarning from DATE etc.
+        wcs = WCS(header)
+    return Frame(image_e, satmask, catalog, wcs, meta)

wcc_phot/lightcurve.py

@@ -0,0 +1,103 @@
+"""Differential light curve from the per-star, per-frame measurement table."""
+
+import warnings
+
+import numpy as np
+from astropy.table import Table
+
+from .flags import FLAG_NOFLUX
+
+
+def ensemble_ratio(flux_t, err_t, ref_flux, ref_err):
+    """Target / reference-ensemble flux for one frame.
+
+    Returns (rel, rel_err, flux_ens, err_ens, ok). The ensemble is the sum
+    of the given reference fluxes. The error uses
+    var(T/R) = var(T)/R^2 + T^2 var(R)/R^4, which never divides by the
+    target flux, so a zero target is a valid measurement of zero rather
+    than a ZeroDivisionError. `ok` is False, and rel/rel_err are NaN, when
+    the target flux is not finite or the ensemble is not finite or <= 0.
+    """
+    flux_t, err_t = float(flux_t), float(err_t)
+    ref_flux = np.asarray(ref_flux, dtype=float)
+    ref_err = np.asarray(ref_err, dtype=float)
+    flux_ens = float(np.sum(ref_flux))
+    err_ens = float(np.sqrt(np.sum(ref_err**2)))
+    ok = bool(np.isfinite(flux_t) and np.isfinite(flux_ens) and flux_ens > 0)
+    if not ok:
+        return np.nan, np.nan, flux_ens, err_ens, False
+    rel = flux_t / flux_ens
+    rel_err = np.sqrt(err_t**2 / flux_ens**2 + flux_t**2 * err_ens**2 / flux_ens**4)
+    return rel, float(rel_err), flux_ens, err_ens, True
+
+
+def usable_references(measurements):
+    """Star indices of the references with flags == 0 in every frame.
+
+    A fixed subset keeps the ensemble baseline stable: dropping a reference
+    from some frames only would step the light curve by that star's share
+    of the ensemble, an artificial transit. If no reference is clean in
+    every frame, all of them are used and a warning says so.
+    """
+    refs = measurements[measurements["role"] == "ref"]
+    stars = np.unique(np.asarray(refs["star"]))
+    clean = [
+        int(s) for s in stars
+        if not np.any(np.asarray(refs["flags"][refs["star"] == s]) != 0)
+    ]
+    if not clean and len(stars):
+        warnings.warn(
+            "every reference star is flagged in at least one frame; using "
+            "all of them in the ensemble",
+            UserWarning,
+        )
+        clean = [int(s) for s in stars]
+    return clean
+
+
+def build_lightcurve(measurements, refs=None):
+    """One row per frame: target, reference-ensemble, and relative fluxes.
+
+    The ensemble is the straight sum of the usable reference fluxes
+    (`refs`, default `usable_references`); rel_flux = flux_target /
+    flux_ens with errors propagated (see `ensemble_ratio`), and
+    rel_flux_norm is rel_flux divided by its median over the frames where
+    it is defined. A frame whose ratio is undefined keeps its row with NaN
+    fluxes and FLAG_NOFLUX set instead of aborting the series. `flags` is
+    the target's own flags plus FLAG_NOFLUX; reference flags are reported
+    through the selection, not here.
+    """
+    if refs is None:
+        refs = usable_references(measurements)
+    refs = np.asarray(refs, dtype=int)
+    rows = []
+    for k in np.unique(measurements["frame"]):
+        mk = measurements[measurements["frame"] == k]
+        target = mk[mk["role"] == "target"][0]
+        ref_rows = mk[(mk["role"] == "ref") & np.isin(mk["star"], refs)]
+        rel, rel_err, flux_ens, err_ens, ok = ensemble_ratio(
+            target["flux_e"], target["flux_err_e"],
+            ref_rows["flux_e"], ref_rows["flux_err_e"],
+        )
+        rows.append(
+            {
+                "frame": int(k),
+                "time": float(target["time"]),
+                "flux_target": float(target["flux_e"]),
+                "flux_target_err": float(target["flux_err_e"]),
+                "flux_ens": flux_ens,
+                "flux_ens_err": err_ens,
+                "rel_flux": rel,
+                "rel_flux_err": rel_err,
+                "n_ref": len(ref_rows),
+                "flags": int(target["flags"]) | (0 if ok else FLAG_NOFLUX),
+            }
+        )
+    lc = Table(rows)
+    rel = np.asarray(lc["rel_flux"], dtype=float)
+    median = float(np.nanmedian(rel)) if np.isfinite(rel).any() else np.nan
+    if not (np.isfinite(median) and median != 0):
+        median = np.nan
+    lc["rel_flux_norm"] = rel / median
+    lc["rel_flux_norm_err"] = np.asarray(lc["rel_flux_err"], dtype=float) / median
+    return lc

wcc_phot/live.py

@@ -0,0 +1,141 @@
+"""Live matplotlib view of the photometry as each frame is analyzed.
+
+Pass a LiveViewer as `run_photometry(..., on_frame=viewer)` (or use the
+CLI `--live` flag): the left panel shows the current frame with the
+target (red) and reference (teal) apertures at their re-centroided
+positions, the right panel grows the relative light curve point by
+point. Any callable accepting the same event dict works as `on_frame`,
+so custom displays (GUIs, DS9, web) can hook in the same way.
+"""
+
+import warnings
+
+import numpy as np
+from wcc_sim.plotting import REF_COLOR, TARGET_COLOR  # noqa: F401
+
+
+class LiveViewer:
+    """Interactive two-panel display updated once per analyzed frame."""
+
+    def __init__(self, pause=0.2, percent=99.5, cmap="gray_r", zoom=None):
+        """`zoom` (px, optional) crops the image panel around the target."""
+        self.pause = pause
+        self.percent = percent
+        self.cmap = cmap
+        self.zoom = zoom
+        self._fig = None
+
+    # -- pipeline callback ------------------------------------------------
+    def __call__(self, event):
+        import matplotlib.pyplot as plt
+
+        if self._fig is None:
+            self._setup(event)
+        self._update(event)
+        self._fig.canvas.draw_idle()
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")  # non-GUI backend chatter
+            plt.pause(self.pause)
+
+    def hold(self):
+        """Keep the window open after the run (no-op without a figure)."""
+        import matplotlib.pyplot as plt
+
+        if self._fig is not None:
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore")
+                plt.ioff()
+                plt.show()
+
+    def close(self):
+        import matplotlib.pyplot as plt
+
+        if self._fig is not None:
+            plt.close(self._fig)
+            self._fig = None
+
+    # -- internals ---------------------------------------------------------
+    def _setup(self, event):
+        import matplotlib.pyplot as plt
+        from astropy.visualization import simple_norm
+
+        plt.ion()
+        self._fig, (self._ax_img, self._ax_lc) = plt.subplots(
+            1, 2, figsize=(12, 5.5), width_ratios=[1.15, 1]
+        )
+        self._norm = simple_norm(event["image_e"], "asinh", percent=self.percent)
+        self._im = self._ax_img.imshow(
+            event["image_e"], origin="lower", cmap=self.cmap, norm=self._norm
+        )
+        if self.zoom is not None:
+            x0, y0 = event["x"][0], event["y"][0]
+            self._ax_img.set_xlim(x0 - self.zoom, x0 + self.zoom)
+            self._ax_img.set_ylim(y0 - self.zoom, y0 + self.zoom)
+        self._ax_img.set_xlabel("x [px]")
+        self._ax_img.set_ylabel("y [px]")
+
+        from matplotlib.patches import Circle
+
+        geom = event["geom"]
+        self._circles = []
+        for j, role in enumerate(event["roles"]):
+            color = TARGET_COLOR if role == "target" else REF_COLOR
+            circle = Circle(
+                (event["x"][j], event["y"][j]),
+                geom.r_ap,
+                fill=False,
+                color=color,
+                lw=1.4,
+            )
+            self._ax_img.add_patch(circle)
+            self._circles.append(circle)
+        self._annuli = []
+        for radius in (geom.r_in, geom.r_out):
+            ring = Circle(
+                (event["x"][0], event["y"][0]),
+                radius,
+                fill=False,
+                color=TARGET_COLOR,
+                lw=0.8,
+                ls="--",
+                alpha=0.7,
+            )
+            self._ax_img.add_patch(ring)
+            self._annuli.append(ring)
+
+        self._times, self._rel, self._rel_err = [], [], []
+        self._ax_lc.set_xlabel("time")
+        self._ax_lc.set_ylabel("target / ref ensemble")
+        self._fig.tight_layout()
+
+    def _update(self, event):
+        self._im.set_data(event["image_e"])
+        for circle, x, y in zip(self._circles, event["x"], event["y"]):
+            circle.center = (x, y)
+        for ring in self._annuli:
+            ring.center = (event["x"][0], event["y"][0])
+        self._ax_img.set_title(
+            f"frame {event['frame'] + 1}/{event['n_frames']}"
+        )
+
+        self._times.append(event["time"])
+        self._rel.append(event["rel_flux"])
+        self._rel_err.append(event["rel_flux_err"])
+        self._ax_lc.clear()
+        self._ax_lc.errorbar(
+            self._times,
+            self._rel,
+            yerr=self._rel_err,
+            fmt="o",
+            color=TARGET_COLOR,
+            ecolor=REF_COLOR,
+            capsize=2,
+        )
+        median = float(np.median(self._rel))
+        self._ax_lc.axhline(median, color=REF_COLOR, lw=0.8, ls=":")
+        self._ax_lc.set_xlabel("time")
+        self._ax_lc.set_ylabel("target / ref ensemble")
+        self._ax_lc.set_title(
+            f"rel flux = {event['rel_flux']:.5f} "
+            f"± {event['rel_flux_err']:.5f}"
+        )