corona3d 0.1.2__py3-none-any.whl

corona3d/__init__.py

@@ -0,0 +1,23 @@
+"""corona3d: physics-based, reproducible three-dimensional reconstruction of the solar corona,
+coronal mass ejections, and radio sources for any event from public MHD, coronagraph, and radio
+data, with its own field-line tracer, a parameter-free selection of the streamer loops, an automated
+GCS fit with a stated quality, and a record of what was measured and what was assumed."""
+__version__ = "0.1.2"
+
+from .layers import LAYERS, ON  # noqa: E402
+from .paths import config as load_config  # noqa: E402
+
+__all__ = ["LAYERS", "ON", "make_figure", "reconstruct", "newkirk_r", "load_config", "build", "export",
+           "Reconstruction", "__version__"]
+
+_LAZY = {"make_figure": "reconstruction", "reconstruct": "reconstruction", "newkirk_r": "reconstruction",
+         "build": "api", "Reconstruction": "api", "export": "exporting"}
+
+
+def __getattr__(name):
+    """The functions that need PyVista, SunPy, or VTK are imported only when first used."""
+    if name in _LAZY:
+        from importlib import import_module
+        mod = import_module(f".{_LAZY[name]}", __name__)
+        return getattr(mod, name)
+    raise AttributeError(name)

corona3d/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

corona3d/_extras.py

@@ -0,0 +1,37 @@
+"""Optional dependencies: each heavy package is imported where it is first needed, and a missing one
+stops with the name of the extra that installs it (`pip install "corona3d[render]"`)."""
+from importlib import import_module
+
+EXTRAS = {                                   # extra: the packages (import name, pip name) it installs
+    "render": [("pyvista", "pyvista"), ("PyThea", "PyThea")],
+    "gcs": [("PyThea", "PyThea"), ("skimage", "scikit-image")],
+    "radio": [("h5py", "h5py")],
+}
+
+
+class MissingExtra(ImportError):
+    """An optional package is not installed; the message names the extra."""
+
+
+def need(extra, module, what):
+    """Import `module` for `what`; on failure raise MissingExtra naming the extra to install."""
+    try:
+        return import_module(module)
+    except ImportError as e:
+        raise MissingExtra(f"{what} needs the package {module}, which is not installed. "
+                           f"Install it with: pip install \"corona3d[{extra}]\"  (or corona3d[all])") from e
+
+
+def status():
+    """{extra: {package: version or None}} for the optional extras."""
+    from importlib import metadata
+    out = {}
+    for extra, pk in EXTRAS.items():
+        out[extra] = {}
+        for mod, pip in pk:
+            try:
+                import_module(mod)
+                out[extra][pip] = metadata.version(pip)
+            except Exception:
+                out[extra][pip] = None
+    return out

corona3d/animate.py

@@ -0,0 +1,223 @@
+"""Animations of the reconstruction (`corona3d animate`): one frame per time, as a GIF and an MP4.
+
+Every frame is the figure of `corona3d render` at the frame time: the shell has the apex height that a height
+law gives for that time, and the radio sources accumulate up to it. The model surface and the field lines are
+computed once, the cameras, the colour limits, the panel scale, and the radio time range are fixed for the whole
+animation, and the frame time is written on the figure. A GIF holds 256 colours, so one palette is built for all
+frames (`shared_palette`).
+"""
+import csv
+import shutil
+import subprocess
+from datetime import timedelta
+from pathlib import Path
+
+import numpy as np
+
+R_SUN_KM = 695700.0
+
+
+def parse_height_points(text):
+    """'2013-10-25T15:00=1.931,2013-10-25T15:24=5.538' -> [(datetime, height [R_sun])]."""
+    from .whitelight import utc
+    try:
+        return [(utc(t), float(h)) for t, h in (x.rsplit("=", 1) for x in text.split(","))]
+    except ValueError:
+        raise ValueError(f"{text!r}: give TIME=HEIGHT pairs, e.g. 2013-10-25T15:00=1.931,2013-10-25T15:24=5.538")
+
+
+def read_heights(path):
+    """Measured heights from a CSV file of two columns, time (ISO) and apex height [R_sun]; a header line and
+    lines starting with # are skipped."""
+    from .whitelight import utc
+    pts = []
+    for row in csv.reader(l for l in Path(path).read_text(encoding="utf-8").splitlines() if l.strip() and l[0] != "#"):
+        try:
+            pts.append((utc(row[0].strip()), float(row[1])))
+        except (ValueError, IndexError):
+            if pts:
+                raise ValueError(f"{path}: cannot read the line {row}")        # only the header may be unreadable
+    if len(pts) < 2:
+        raise ValueError(f"{path}: at least two (time, height) lines are needed")
+    return sorted(pts)
+
+
+def height_law(p, fits=None, speed_km_s=None, anchor=None, table=None):
+    """Function from a time (datetime) to the apex height of the shell [R_sun].
+
+    table: measured (time, height) points (EUV or Solar Orbiter), interpolated linearly, valid only between the
+    first and the last of them. speed_km_s: constant speed from anchor, one (time, height) point (default: the
+    shell of the configuration at its time). fits: two (time, height) points, for example the two GCS fits, with
+    a straight line through them (also beyond them). Default: the line through the shell `gcs` at the time of
+    the reconstruction and the shell `gcs_wl` at its own time, the two fits of the configuration."""
+    from .whitelight import utc
+    if table:
+        t, h = zip(*sorted(table))
+        s = np.array([(x - t[0]).total_seconds() for x in t])
+        def law(time):
+            x = (time - t[0]).total_seconds()
+            if not s[0] <= x <= s[-1]:
+                raise ValueError(f"{time:%Y-%m-%d %H:%M:%S} UT is outside the measured heights ({t[0]:%H:%M:%S} to "
+                                 f"{t[-1]:%H:%M:%S} UT); change --start and --end, or use a line or a speed")
+            return float(np.interp(x, s, h))
+        return law
+    if speed_km_s is not None:
+        t0, h0 = anchor or (utc((p.get("gcs_fit") or {}).get("t_out") or p["time"]), p["gcs"]["height"])
+        return lambda time: h0 + speed_km_s * (time - t0).total_seconds() / R_SUN_KM
+    if fits is None:
+        g, w = p["gcs"], p.get("gcs_wl")
+        if not w or "time" not in w:
+            raise ValueError("the configuration has one shell only: give --height-fits, --speed, or --heights")
+        fits = [(utc((p.get("gcs_fit") or {}).get("t_out") or p["time"]), g["height"]), (utc(w["time"]), w["height"])]
+    (t0, h0), (t1, h1) = fits
+    if t0 == t1:
+        raise ValueError("the two fits are at the same time")
+    return lambda time: h0 + (h1 - h0) * (time - t0).total_seconds() / (t1 - t0).total_seconds()
+
+
+def frame_times(start, end, step_s):
+    """Times from start to end (inclusive) in steps of step_s seconds."""
+    if step_s <= 0 or end < start:
+        raise ValueError("give --step above zero and --end not before --start")
+    n = int((end - start).total_seconds() // step_s)
+    return [start + timedelta(seconds=step_s * i) for i in range(n + 1)]
+
+
+def reserved_colours(p, n_max=200):
+    """The colours that every frame needs exactly, as uint8 (n x 3): the v_A colour map (Spectral_r, 40 steps)
+    and two copies in the shade of the surface (0.75 and 0.5 of the brightness), the light-to-dark ramp of every
+    radio colour (12 steps), the shell colour, the purple of the streamer lines, black, and white."""
+    from matplotlib import colormaps, colors
+    from .reconstruction import chain_colours
+    sp = colormaps["Spectral_r"](np.linspace(0, 1, 40))[:, :3]
+    single = np.array([colors.to_rgb(c) for c in (p["mesh_rings"]["color"], "#9a6fc0", "#000000", "#ffffff")])
+    base = p.get("radio_colors") or []
+    n_ramp = min(12, max(2, (n_max - 120 - len(single)) // max(len(base), 1)))
+    ramps = [chain_colours(c, np.linspace(0, 1, n_ramp)) for c in base]
+    return (np.vstack([sp, sp * 0.75, sp * 0.5, *ramps, single]) * 255).round().astype(np.uint8)
+
+
+def shared_palette(frames, reserved, n_total=256):
+    """One 256-colour palette image for all frames: the reserved colours, then a median cut of the frames for
+    the rest. Mostly grey frames would make a palette of each frame spend its colours on greys and shift the
+    v_A and radio colours from frame to frame."""
+    from PIL import Image
+    n_rest = n_total - len(reserved)
+    sample = np.vstack([f[::2, ::2] if f.shape[0] * f.shape[1] > 10**6 else f for f in frames])
+    both = Image.fromarray(np.ascontiguousarray(sample).reshape(-1, sample.shape[1], 3))
+    rest = both.quantize(colors=n_rest, method=Image.Quantize.MEDIANCUT, dither=Image.Dither.NONE).convert("RGB")
+    rest = np.unique(np.asarray(rest).reshape(-1, 3), axis=0)[:n_rest]
+    pal = np.vstack([reserved, rest])
+    pimg = Image.new("P", (1, 1))
+    pimg.putpalette(list(pal.ravel()) + [0] * (768 - pal.size))
+    return pimg
+
+
+def save_gif(frames, path, fps, reserved, scale=0.5):
+    """Write the RGB frames (uint8 arrays) as a GIF with one shared palette and no dithering."""
+    from PIL import Image
+    imgs = [Image.fromarray(f) for f in frames]
+    if scale != 1:
+        imgs = [i.resize((max(1, round(i.width * scale)), max(1, round(i.height * scale))), Image.Resampling.LANCZOS)
+                for i in imgs]
+    pimg = shared_palette([np.asarray(i) for i in imgs], reserved)
+    q = [i.quantize(palette=pimg, dither=Image.Dither.NONE) for i in imgs]
+    q[0].save(path, save_all=True, append_images=q[1:], duration=round(1000 / fps), loop=0, optimize=False)
+    return Path(path)
+
+
+def ffmpeg_exe():
+    """The ffmpeg of the package imageio-ffmpeg, or else the one on the path."""
+    try:
+        import imageio_ffmpeg
+        return imageio_ffmpeg.get_ffmpeg_exe()
+    except Exception:
+        exe = shutil.which("ffmpeg")
+        if exe:
+            return exe
+    raise RuntimeError("an MP4 needs ffmpeg: install it with pip install \"corona3d[animate]\" (the package "
+                       "imageio-ffmpeg) or put ffmpeg on the path")
+
+
+def save_mp4(frames, path, fps):
+    """Write the RGB frames as an H.264 MP4 (libx264, yuv420p; the size is cut to even numbers)."""
+    h, w = frames[0].shape[0] // 2 * 2, frames[0].shape[1] // 2 * 2
+    cmd = [ffmpeg_exe(), "-y", "-loglevel", "error", "-f", "rawvideo", "-pix_fmt", "rgb24", "-s", f"{w}x{h}",
+           "-r", str(fps), "-i", "-", "-c:v", "libx264", "-pix_fmt", "yuv420p", "-crf", "18",
+           "-movflags", "+faststart", str(path)]
+    proc = subprocess.Popen(cmd, stdin=subprocess.PIPE, stderr=subprocess.PIPE)
+    try:
+        for f in frames:
+            proc.stdin.write(np.ascontiguousarray(f[:h, :w]).tobytes())
+        proc.stdin.close()
+        err = proc.stderr.read().decode(errors="replace")
+    finally:
+        proc.wait()
+    if proc.returncode:
+        raise RuntimeError(f"ffmpeg failed: {err[-500:]}")
+    return Path(path)
+
+
+def animate(out="figures/corona3d_animation", data_root=".", start=None, end=None, step_s=None, fps=2.0,
+            gif=True, mp4=False, half=None, params=None, panels=None, layout="landscape", law=None,
+            gif_scale=0.5, **layers):
+    """Render one frame per time from start to end (ISO texts; default: the radio images of the configuration)
+    and write out.gif and/or out.mp4 (for layout "separate", one animation per view, out_VIEW.gif).
+    law: function from a time to the apex height (height_law; default: the line through the two shells of
+    the configuration). The other arguments are those of make_figure. Returns the list of files."""
+    from . import reconstruction as rc
+    from .layers import ON
+    from .paths import config, merge
+    from .whitelight import utc
+    bad = set(layers) - set(rc.LAYERS)
+    if bad:
+        raise ValueError(f"unknown layers {sorted(bad)}; choose from {', '.join(rc.LAYERS)}")
+    if half is not None and half <= 0:
+        raise ValueError("half must be positive")
+    on = dict(ON, **layers)
+    p0 = merge(config(data_root), params)
+    rc.check_opacity(dict(p0["opacity"], **({"wl": p0["wl_opacity"]} if "wl_opacity" in p0 else {})))
+    ri = p0["radio_images"] if on["radio"] else []
+    if start is None or end is None:
+        if not ri:
+            raise ValueError("give --start and --end")
+        start = start or min((rs["start"] for rs in ri), key=utc)
+        end = end or max((rs["end"] for rs in ri), key=utc)
+    step_s = step_s or (ri[0]["step_s"] if ri else 60.0)
+    times = frame_times(utc(start), utc(end), step_s)
+    law = law or height_law(p0)
+    rc.select_views(p0, panels)
+    out = Path(out) if Path(out).is_absolute() else Path(data_root) / out
+    out.parent.mkdir(parents=True, exist_ok=True)
+    # one colour scale of the radio time for every frame, from the first radio image to the last frame
+    rng = p0.get("radio_time_range") or ([min((rs["start"] for rs in ri), key=utc), times[-1].isoformat()] if ri else None)
+    cache, frames = {}, []
+    for t in times:                                        # pass 1: the layers of every frame
+        iso = t.isoformat()
+        h = law(t)
+        if h <= 1.0:
+            raise ValueError(f"{iso}: the height law gives {h:.2f} R_sun, below the solar surface")
+        pf = dict(p0, time=iso, anim=dict(height=h), radio_time_range=rng, _png_dir=None,
+                  radio_images=[dict(rs, end=iso) for rs in p0["radio_images"]])
+        sc = rc.reconstruct(pf, on, data_root, cache)
+        sc["times"]["frame"] = iso
+        frames.append((pf, sc))
+        print(f"{iso[11:19]} UT: shell height {h:.3f} R_sun")
+    # a coronagraph image keeps one grey scale: the largest 98th percentile of all frames
+    clim = {i: max(np.nanpercentile(np.abs(sc[i]["wl"]), 98) for _, sc in frames) for i in rc.WL if on[i]}
+    pix = {}
+    for pf, sc in frames:                                  # pass 2: the panels, with fixed cameras and limits
+        pf["wl_clim"] = clim
+        for key, fig in rc.compose(sc, on, pf, half, panels, layout):
+            pix.setdefault(key, []).append(rc.fig_array(fig))
+    res = reserved_colours(p0)
+    files = []
+    for key, arrs in pix.items():
+        base = out if key is None else out.with_name(f"{out.name}_{key}")
+        if gif or not mp4:
+            files.append(save_gif(arrs, base.with_name(base.name + ".gif"), fps, res, gif_scale))
+        if mp4:
+            files.append(save_mp4(arrs, base.with_name(base.name + ".mp4"), fps))
+    for f in files:
+        print("saved", f)
+    return files

corona3d/api.py

@@ -0,0 +1,176 @@
+"""Analysis without the figure: every layer of the reconstruction as arrays.
+
+``build`` reads the working directory's configuration and returns a :class:`Reconstruction`,
+which holds the density surface, the field lines, the CME shell, the radio sources, and the
+observers as NumPy arrays. The layers are those of ``corona3d render`` (they are built by the
+same code), and ``corona3d.exporting`` writes them to files.
+
+Coordinate frame and units of every position: Heliographic Carrington Cartesian, centred on the
+Sun, X towards Carrington longitude 0, Z towards solar north, in solar radii (R_sun). The frame
+rotates with the Sun; the observers are given by their Carrington longitude and latitude at the
+time of the reconstruction. Plane-of-sky positions (``x_rsun``, ``y_rsun``) are seen from Earth,
+x towards the west and y towards solar north.
+"""
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from .layers import LAYERS, ON
+from .paths import config as load_config
+
+__all__ = ["Reconstruction", "build", "load_config", "carrington_angles", "FRAME", "UNITS"]
+
+FRAME = "Heliographic Carrington Cartesian, Sun-centred, X to longitude 0, Z to solar north"
+UNITS = {"position": "R_sun", "angle": "deg", "va": "km/s", "ne": "cm^-3", "tb": "K"}
+RADIO_COLUMNS = ("instrument", "freq_mhz", "time_utc", "x_rsun", "y_rsun", "x_arcsec", "y_arcsec", "tb_k",
+                 "r_rsun", "height_rsun", "x", "y", "z", "lon_carrington_deg", "lat_deg",
+                 "lon_stonyhurst_deg")
+
+
+@dataclass
+class Reconstruction:
+    """The layers of one reconstruction (``None`` or empty when a layer is switched off).
+
+    Attributes
+    ----------
+    config : dict
+        The configuration used (defaults, config.json, and the parameters passed to ``build``).
+    layers : dict
+        Layer name -> bool, as used.
+    surface : dict or None
+        ``vertices`` (n, 3) [R_sun, Carrington Cartesian], ``faces`` (m, 3) indices of triangles,
+        ``va_kms`` (n,) Alfven speed [km/s] and ``ne_cm3`` (n,) electron density [cm^-3] per
+        vertex (the iso-surface of ``ne_level``, rotated by ``model_dlon``).
+    lines : dict
+        ``open``, ``closed``, ``streamer``: lists of (k, 3) arrays [R_sun, Carrington Cartesian],
+        drawn within ``line_r_max``. The streamer lines are the closed lines through the CME shell.
+    gcs : dict
+        Name (``time``, and ``image`` when ``gcs_wl`` is configured) -> dict with ``time`` (ISO)
+        and ``rings`` (n_axis, n_circle, 3) [R_sun, Carrington Cartesian].
+    radio : dict
+        Columns ``RADIO_COLUMNS`` as equal-length arrays, one row per source position. Rows of
+        ``radio_sources`` of the configuration have ``tb_k`` = NaN and an empty time.
+    observers : dict
+        ``earth`` and ``stereo`` -> ``lon_deg``, ``lat_deg`` (Carrington) and ``direction``
+        (unit vector from Sun centre towards the observer, Carrington Cartesian).
+    whitelight : dict
+        Instrument -> ``points`` (n, 3) [R_sun], ``wl`` (n,), ``dims`` (3,), ``time``, ``base_time``.
+    times : dict
+        Times used by the layers, as returned by ``reconstruct``.
+    """
+    config: dict
+    layers: dict
+    surface: dict = None
+    lines: dict = field(default_factory=lambda: dict(open=[], closed=[], streamer=[]))
+    gcs: dict = field(default_factory=dict)
+    radio: dict = field(default_factory=dict)
+    observers: dict = field(default_factory=dict)
+    whitelight: dict = field(default_factory=dict)
+    times: dict = field(default_factory=dict)
+
+
+def carrington_angles(xyz):
+    """Carrington longitude and latitude of points.
+
+    Parameters
+    ----------
+    xyz : array_like, shape (n, 3)
+        Positions [R_sun], Carrington Cartesian.
+
+    Returns
+    -------
+    lon, lat, r : ndarray, shape (n,)
+        Longitude in [0, 360) deg, latitude in deg, distance from Sun centre in R_sun.
+    """
+    xyz = np.atleast_2d(xyz)
+    r = np.linalg.norm(xyz, axis=1)
+    return (np.degrees(np.arctan2(xyz[:, 1], xyz[:, 0])) % 360.0,
+            np.degrees(np.arcsin(np.clip(xyz[:, 2] / r, -1, 1))), r)
+
+
+def _observers(p):
+    from .geometry import unit_vec
+    return {k: dict(lon_deg=float(p[k][0]), lat_deg=float(p[k][1]), direction=unit_vec(*p[k]))
+            for k in ("earth", "stereo")}
+
+
+def _radio_table(sc, p):
+    """Radio positions with their sky-plane and Carrington coordinates (radio_sources first)."""
+    from astropy import units as u
+    from sunpy.coordinates import sun
+    rows = []
+    rs = sun.angular_radius(p["time"]).to_value(u.arcsec)
+    for s, (f, xyz, _) in zip(p["radio_sources"], sc.get("radio", [])[:len(p["radio_sources"])]):
+        k = 1.0 / rs if s.get("unit") == "arcsec" else 1.0
+        for x, y, q in zip(np.atleast_1d(s["x"]) * k, np.atleast_1d(s["y"]) * k, xyz):
+            rows.append(("user", f, "", x, y, np.nan, q))
+    for b in sc.get("radio_blobs", []):
+        for t, x, y, tb, q in zip(b["time"], b["x"], b["y"], b["tb"], b["xyz"]):
+            rows.append((b["instrument"], b["freq"], t.isoformat(), x, y, tb, q))
+    cols = {c: [] for c in RADIO_COLUMNS}
+    if rows:
+        xyz = np.array([r[6] for r in rows])
+        lon, lat, r = carrington_angles(xyz)
+        for (inst, f, t, x, y, tb, _), q, lo, la, rr in zip(rows, xyz, lon, lat, r):
+            vals = (inst, f, t, x, y, x * rs, y * rs, tb, rr, rr - 1.0, *q, lo, la,
+                    (lo - p["earth"][0] + 180.0) % 360.0 - 180.0)
+            for c, v in zip(RADIO_COLUMNS, vals):
+                cols[c].append(v)
+    return {c: np.array(v, dtype=str if c in ("instrument", "time_utc") else float) for c, v in cols.items()}
+
+
+def build(home=".", params=None, **layers):
+    """Build the reconstruction of a working directory and return its layers as arrays.
+
+    Parameters
+    ----------
+    home : str or Path
+        Working directory (its ``config.json`` is read; the data are in ``data/`` below it).
+    params : dict, optional
+        Configuration keys that replace those of ``config.json`` (nested keys may be partial).
+    **layers : bool
+        Any of ``LAYERS`` as True or False; the defaults are those of ``corona3d render``
+        (the coronagraph layers and ``radio`` are off). ``sphere`` has no data and is ignored.
+
+    Returns
+    -------
+    Reconstruction
+        Positions in R_sun (Carrington Cartesian), Alfven speed in km/s, density in cm^-3,
+        angles in degrees; see :class:`Reconstruction` for the shapes.
+
+    Raises
+    ------
+    ValueError
+        For a layer name that is not in ``LAYERS``.
+    FileNotFoundError
+        When a layer needs data that are missing (``corona3d fetch``).
+    """
+    from . import reconstruction as rc
+    from .paths import merge
+    bad = set(layers) - set(LAYERS)
+    if bad:
+        raise ValueError(f"unknown layers {sorted(bad)}; choose from {', '.join(LAYERS)}")
+    on = dict(ON, **layers)
+    p = merge(load_config(home), params)
+    sc = rc.reconstruct(p, dict(on, gcs=False), home)
+    rec = Reconstruction(config=p, layers=on, times=sc["times"], observers=_observers(p))
+    if "surface" in sc:
+        s = sc["surface"]
+        rec.surface = dict(vertices=np.asarray(s.points, float), faces=s.faces.reshape(-1, 4)[:, 1:].copy(),
+                           va_kms=np.asarray(s["va"], float), ne_cm3=np.asarray(s["ne"], float))
+    for k in rec.lines:
+        rec.lines[k] = sc.get(k, [])
+    if on["gcs"]:
+        rec.gcs["time"] = dict(time=p["time"], rings=rc.shell_of(p["gcs"], p, p["time"]))
+        if p.get("gcs_wl"):
+            t = p["gcs_wl"]["time"]
+            rec.gcs["image"] = dict(time=t, rings=rc.shell_of(p["gcs_wl"], p, t))
+    if on["radio"]:
+        rec.radio = _radio_table(sc, p)
+    for inst in rc.WL:
+        if on[inst]:
+            g = sc[inst]
+            rec.whitelight[inst] = dict(points=np.asarray(g.points, float), wl=np.asarray(g["wl"], float),
+                                        dims=np.array(g.dimensions), time=sc["times"][inst][0].isoformat(),
+                                        base_time=sc["times"][inst][1].isoformat())
+    return rec

corona3d/bursts.py

@@ -0,0 +1,110 @@
+"""Type II and type III radio bursts of a day from the edited event list of NOAA SWPC.
+
+When `corona3d event` is given only a date, the burst times of that day are listed and the user
+chooses one with `--burst N`. The source is the daily file `YYYYMMDDevents.txt` of the SWPC edited
+events (patrol reports of ground radio observatories, code RSP), kept by NOAA NCEI since 1996 and reachable without a login at
+https://www.ngdc.noaa.gov/stp/space-weather/swpc-products/daily_reports/solar_event_reports/ ;
+the recent files are also on ftp://ftp.swpc.noaa.gov/pub/indices/events/ (used as a fallback).
+A line of type RSP gives the begin and end time [UT], the observatory, the frequency range [MHz],
+the burst type (II, III, IV, V, VI, CTM with an intensity class) and, for type II, the shock speed [km/s].
+"""
+import re
+import urllib.request
+from datetime import datetime, timedelta
+from pathlib import Path
+
+NCEI = ("https://www.ngdc.noaa.gov/stp/space-weather/swpc-products/daily_reports/solar_event_reports/"
+        "{y}/{m}/{d}events.txt")
+FTP = "ftp://ftp.swpc.noaa.gov/pub/indices/events/{d}events.txt"
+TYPES = ("II", "III")
+DATE = re.compile(r"\d{4}-\d{2}-\d{2}")
+
+
+def is_date(text):
+    """True for a date without a time, e.g. 2024-05-09."""
+    return bool(DATE.fullmatch(text.strip()))
+
+
+def parse(text, day):
+    """Burst rows [dict(type, begin, end, obs, freq_mhz, speed_km_s)] of the RSP lines of a SWPC
+    event file for the date `day` (datetime.date or 'YYYY-MM-DD'), in time order. A begin or end
+    time may carry a flag letter (A, B, D, U) and an end of '////' is missing; the end then is None."""
+    day = datetime.fromisoformat(str(day)).date()
+    rows = []
+    for line in text.splitlines():
+        p = line.split()
+        if len(p) < 3 or line.startswith(("#", ":")) or "RSP" not in p:
+            continue
+        i = p.index("RSP")
+        if i < 5 or i + 2 >= len(p):                                # ..., begin, max, end, observatory, quality, RSP, range, type
+            continue
+        begin, end = (re.sub(r"^[A-Z]", "", p[i - k]) for k in (5, 3))
+        if not re.fullmatch(r"\d{4}", begin):
+            continue
+        midnight = datetime.combine(day, datetime.min.time())
+        clock = lambda t: midnight + timedelta(hours=int(t[:2]), minutes=int(t[2:]))
+        kind = p[i + 2].split("/")[0]
+        speed = float(p[i + 3]) if kind == "II" and len(p) > i + 3 and re.fullmatch(r"\d+(\.\d+)?", p[i + 3]) else None
+        t_end = clock(end) if re.fullmatch(r"\d{4}", end) else None
+        if t_end is not None and t_end < clock(begin):               # the burst crosses midnight
+            t_end += timedelta(days=1)
+        rows.append(dict(type=kind, begin=clock(begin), end=t_end,
+                         obs=p[i - 2], freq_mhz=p[i + 1], speed_km_s=speed))
+    return sorted(rows, key=lambda r: r["begin"])
+
+
+def select(rows, types=TYPES):
+    """The rows whose burst type is in `types` (default II and III)."""
+    return [r for r in rows if r["type"] in types]
+
+
+def fetch(day, home=None, opener=urllib.request.urlopen):
+    """Text of the SWPC event file of `day`, from the cache folder data/bursts of `home` when present;
+    otherwise from NCEI and, if that fails, from the SWPC FTP server. Raises RuntimeError with both reasons."""
+    day = datetime.fromisoformat(str(day)).date()
+    d = f"{day:%Y%m%d}"
+    cache = Path(home) / "data" / "bursts" / f"{d}events.txt" if home else None
+    if cache and cache.exists():
+        return cache.read_text(encoding="utf-8", errors="replace")
+    why = []
+    for url in (NCEI.format(y=f"{day:%Y}", m=f"{day:%m}", d=d), FTP.format(d=d)):
+        try:
+            with opener(url, timeout=60) as r:
+                text = r.read().decode("utf-8", errors="replace")
+            if "Edited Events" not in text:
+                raise ValueError("not an event file")
+            if cache:
+                cache.parent.mkdir(parents=True, exist_ok=True)
+                cache.write_text(text, encoding="utf-8")
+            return text
+        except Exception as e:
+            why.append(f"{url}: {e}")
+    raise RuntimeError(f"the SWPC event list of {day} could not be fetched ({'; '.join(why)}); "
+                       "give --time with the time of the burst instead")
+
+
+def listing(rows):
+    """Numbered text lines of burst rows, for the user to choose from with --burst."""
+    out = []
+    for n, r in enumerate(rows, 1):
+        end = f"{r['end']:%H:%M}" if r["end"] else "----"
+        sp = f", shock speed {r['speed_km_s']:g} km/s" if r["speed_km_s"] else ""
+        out.append(f"  {n:2d}  type {r['type']:<3s} {r['begin']:%H:%M} to {end} UT  {r['freq_mhz']} MHz  {r['obs']}{sp}")
+    return out
+
+
+def choose(date, burst, home=None, types=TYPES, opener=urllib.request.urlopen, log=print):
+    """Time (ISO text, minutes) of burst number `burst` (1-based) of `date`; with burst None the
+    candidates are listed and None is returned."""
+    rows = select(parse(fetch(date, home, opener), date), types)
+    if not rows:
+        raise RuntimeError(f"no type {'/'.join(types)} burst in the SWPC list of {date}; give --time")
+    if burst is None:
+        log(f"Type {'/'.join(types)} bursts of {date} (SWPC edited events; times are UT):")
+        for t in listing(rows):
+            log(t)
+        log("Choose one with --burst N; its begin time becomes --time (use --time to give another).")
+        return None
+    if not 1 <= burst <= len(rows):
+        raise RuntimeError(f"--burst {burst}: the list of {date} has {len(rows)} bursts")
+    return f"{rows[burst - 1]['begin']:%Y-%m-%dT%H:%M}"