#!/usr/bin/env python3
"""
Timeline of one observing day, from the catalog written by build_catalog.py.

One lane per station, a bar per recording (start to end) in the faded colour of the
waveform family. On the transmitting station's lane the transmission itself is drawn
on top in the full colour. Bars carry a short waveform label when it fits, so no
legend is needed. Other observations (e.g. 3C273) are grey and labelled with the
object name.

In a notebook:
    from plot_timeline import load_catalog, timeline_mpl, timeline_plotly
    tx, rec = load_catalog("catalog")
    fig = timeline_mpl(tx, rec, "2026-10-17")          # static, for the paper
    fig.savefig("timeline_2026-10-17.pdf", bbox_inches="tight")
    timeline_plotly(tx, rec, "2026-10-17").show()       # interactive, hover for details

From the command line:
    python plot_timeline.py catalog/ 2026-10-17 -o timeline_2026-10-17.pdf
    python plot_timeline.py catalog/ 2026-10-17 --html timeline_2026-10-17.html
"""

import argparse
import re
from pathlib import Path

import pandas as pd

# --------------------------------------------------------------------------
# Things to adapt
# --------------------------------------------------------------------------

TX_STATION = "dwingeloo"            # the station that transmits (and always records)
EXCLUDE_OBJECTS = ("GNSS", "X")     # other observations to leave out

# Waveform families: (regex on the category, short label). The position in this
# list fixes the colour, so colours stay the same across days. Unknown categories
# get the remaining colours, labelled with their first word.
FAMILIES = [
    (r"^cw-", "CW"),
    (r"mfsk", "mFSK"),
    (r"^zadoff-chu", "ZC"),
    (r"^q65", "Q65"),
    (r"^morse", "Morse"),
]

# Short station names for the lane labels; others use the station ID, capitalised.
STATION_LABELS = {"dwingeloo": "Dwingeloo", "wsrt": "WSRT"}

# --------------------------------------------------------------------------

PALETTE = ["#2a78d6", "#eb6834", "#1baf7a", "#eda100",
           "#e87ba4", "#008300", "#6250d6", "#e34948"]
OTHER_COLOR = "#9a9893"
INK = "#0b0b0b"
INK_MUTED = "#52514e"
GRID = "#e4e3df"
RX_ALPHA = 0.35           # faded receive bars


def family(category):
    """Short label for a waveform category, e.g. 'zadoff-chu-fs250000-...' -> 'ZC'."""
    if not isinstance(category, str):
        return None
    for pattern, label in FAMILIES:
        if re.search(pattern, category, flags=re.I):
            return label
    return re.split(r"[-_]", category)[0].upper()[:5]


def family_colors(labels):
    """Colour per family: known families by their FAMILIES position, others after."""
    known = [lab for _, lab in FAMILIES]
    extra = sorted(set(labels) - set(known))
    order = known + extra
    return {lab: (PALETTE[i] if i < len(PALETTE) else OTHER_COLOR) for i, lab in enumerate(order)}


def _text_color(hex_color, alpha=1.0):
    """Dark or white text, whichever reads better on the (blended) fill."""
    h = hex_color.lstrip("#")
    rgb = [int(h[i:i + 2], 16) / 255 for i in (0, 2, 4)]
    rgb = [alpha * c + (1 - alpha) * 1.0 for c in rgb]          # blend on white
    lin = [c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4 for c in rgb]
    lum = 0.2126 * lin[0] + 0.7152 * lin[1] + 0.0722 * lin[2]
    return INK if lum > 0.28 else "white"


def parse_times(s):
    """Parse ISO 8601 times, also when precision differs between values."""
    try:
        return pd.to_datetime(s, utc=True, format="ISO8601")   # pandas >= 2.0
    except (ValueError, TypeError):
        return pd.to_datetime(s, utc=True)                      # pandas 1.x


def load_catalog(catalog_dir="catalog"):
    d = Path(catalog_dir)
    tx = pd.read_csv(d / "transmissions.csv")
    rec = pd.read_csv(d / "recordings.csv")
    for df, cols in ((tx, ["tx_time", "tx_end", "rec_end"]), (rec, ["tx_time", "rec_start"])):
        for c in cols:
            df[c] = parse_times(df[c])
    rec["rec_end"] = rec["rec_start"] + pd.to_timedelta(rec["duration_s"], unit="s")
    rec["issues"] = rec["issues"].fillna("")
    tx["issues"] = tx["issues"].fillna("")
    rec["family"] = rec["category"].map(family)
    tx["family"] = tx["category"].map(family)

    # TX length unknown (waveform not in --tx-dir): estimate it as the recording
    # length minus the usual listening time.
    listen = rec["listen_s"].median()
    tx["tx_end_estimated"] = tx["tx_end"].isna()
    if pd.notna(listen):
        tx["tx_end"] = tx["tx_end"].fillna(tx["rec_end"] - pd.to_timedelta(listen, unit="s"))
    return tx, rec


def _select_day(tx, rec, date, exclude_objects):
    date = pd.Timestamp(date).date()
    tx_d = tx[pd.to_datetime(tx["date"]).dt.date == date].sort_values("tx_time")
    rec_d = rec[pd.to_datetime(rec["date"]).dt.date == date]
    rec_d = rec_d[~((rec_d["kind"] != "radar") & rec_d["object"].isin(exclude_objects))]
    rec_d = rec_d[rec_d["rec_start"].notna() & rec_d["rec_end"].notna()].sort_values("rec_start")
    if tx_d.empty and rec_d.empty:
        raise ValueError(f"nothing to plot on {date}")
    return date, tx_d, rec_d


def _lanes(rec_d, tx_station):
    stations = sorted(rec_d["station"].unique())
    if tx_station in stations:
        stations.remove(tx_station)
        stations.insert(0, tx_station)
    return stations


def _station_label(st, tx_station, sep="\n"):
    lab = STATION_LABELS.get(st, st.capitalize())
    return f"{lab}{sep}TX + RX" if st == tx_station else f"{lab}{sep}RX"


def _naive(t):
    """UTC timestamps as naive datetimes (matplotlib and plotly don't need the tz)."""
    return pd.to_datetime(t).dt.tz_convert("UTC").dt.tz_localize(None)


# --------------------------------------------------------------------------
# Static (matplotlib)
# --------------------------------------------------------------------------

def timeline_mpl(tx, rec, date, width=12, tx_station=TX_STATION,
                 exclude_objects=EXCLUDE_OBJECTS, fontsize=8, title=True,
                 start=None, end=None):
    """Static timeline, one lane per station. `width` in inches.
    `start`/`end` (e.g. "10:30") crop the time axis; default is the whole day's data."""
    import matplotlib.dates as mdates
    import matplotlib.pyplot as plt

    date, tx_d, rec_d = _select_day(tx, rec, date, exclude_objects)
    colors = family_colors(set(tx["family"].dropna()) | set(rec["family"].dropna()))
    stations = _lanes(rec_d, tx_station)

    fig, ax = plt.subplots(figsize=(width, 0.55 * len(stations) + 0.9))
    t_min = min(_naive(rec_d["rec_start"]).min(), _naive(tx_d["tx_time"]).min()
                if len(tx_d) else _naive(rec_d["rec_start"]).min())
    t_max = max(_naive(rec_d["rec_end"]).max(), _naive(tx_d["tx_end"]).max()
                if len(tx_d) else _naive(rec_d["rec_end"]).max())
    pad = (t_max - t_min) * 0.01
    t_min, t_max = t_min - pad, t_max + pad
    if start:
        t_min = pd.Timestamp(f"{date} {start}")
    if end:
        t_max = pd.Timestamp(f"{date} {end}")
    ax.set_xlim(mdates.date2num(t_min), mdates.date2num(t_max))
    ax.set_ylim(len(stations) - 0.5, -0.5)
    labels = []   # (x0, width, y, text): drawn at the end, once the layout is final

    h = 0.66
    # Recordings (faded); labelled in the receive-only lanes
    for r, a, b in zip(rec_d.itertuples(), _naive(rec_d["rec_start"]), _naive(rec_d["rec_end"])):
        y = stations.index(r.station)
        radar = r.kind == "radar" and r.family in colors
        col = colors[r.family] if radar else OTHER_COLOR
        alpha = RX_ALPHA if radar else 0.5
        x0, w = mdates.date2num(a), mdates.date2num(b) - mdates.date2num(a)
        ax.broken_barh([(x0, w)], (y - h / 2, h), facecolors=col, alpha=alpha,
                       edgecolor="none")
        ax.broken_barh([(x0, w)], (y - h / 2, h), facecolors="none",
                       edgecolor="white", linewidth=1)
        labels.append((x0, w, y, r.family if radar else r.object))

    # Transmissions (full colour) on the transmitting station's lane
    if tx_station in stations:
        y = stations.index(tx_station)
        for r, a, b in zip(tx_d.itertuples(), _naive(tx_d["tx_time"]), _naive(tx_d["tx_end"])):
            if pd.isna(b) or r.family not in colors:
                continue
            x0, w = mdates.date2num(a), mdates.date2num(b) - mdates.date2num(a)
            ax.broken_barh([(x0, w)], (y - h / 2, h), facecolors=colors[r.family],
                           edgecolor="white", linewidth=1,
                           hatch="////" if r.tx_end_estimated else None)

    ax.set_yticks(range(len(stations)))
    ax.set_yticklabels([_station_label(s, tx_station) for s in stations])
    span_h = (ax.get_xlim()[1] - ax.get_xlim()[0]) * 24
    step = 1 if span_h <= 10 else 2
    ax.xaxis.set_major_locator(mdates.HourLocator(interval=step))
    ax.xaxis.set_minor_locator(mdates.MinuteLocator(byminute=[0, 15, 30, 45] if step == 1 else [0, 30]))
    ax.xaxis.set_major_formatter(mdates.DateFormatter("%H:%M"))
    ax.set_xlabel(f"Time (UTC), {date}", color=INK_MUTED, fontsize=fontsize + 1)
    ax.grid(axis="x", which="major", color=GRID, linewidth=0.8)
    ax.set_axisbelow(True)
    for side in ("top", "right", "left"):
        ax.spines[side].set_visible(False)
    ax.spines["bottom"].set_color(GRID)
    ax.tick_params(axis="y", length=0, labelsize=fontsize + 1, labelcolor=INK)
    ax.tick_params(axis="x", which="both", colors=INK_MUTED, labelsize=fontsize + 1)
    if title:
        ax.set_title(f"Venus radar {date}: {len(tx_d)} transmissions", loc="left",
                     fontsize=fontsize + 2, color=INK)
    fig.tight_layout()

    # Labels centred on each recording (on the TX lane this spans TX + RX; dark ink
    # reads on both the full and the faded colours), only where the text fits.
    fig.canvas.draw()
    days_per_pt = (ax.get_xlim()[1] - ax.get_xlim()[0]) / (ax.bbox.width / fig.dpi * 72)
    for x0, w, y, text in labels:
        if isinstance(text, str) and w / days_per_pt > 0.56 * fontsize * len(text) + 2:
            ax.text(x0 + w / 2, y, text, ha="center", va="center", fontsize=fontsize,
                    color=INK, clip_on=True)
    return fig


# --------------------------------------------------------------------------
# Interactive (plotly)
# --------------------------------------------------------------------------

def _rgba(hex_color, alpha):
    h = hex_color.lstrip("#")
    r, g, b = (int(h[i:i + 2], 16) for i in (0, 2, 4))
    return f"rgba({r},{g},{b},{alpha})"


def _fmt_issues(s):
    return "<br>".join("⚠ " + i for i in s.split(" | ")) if s else ""


def timeline_plotly(tx, rec, date, tx_station=TX_STATION, exclude_objects=EXCLUDE_OBJECTS):
    """Interactive timeline, one lane per station; hover a bar for its details."""
    import plotly.graph_objects as go

    date, tx_d, rec_d = _select_day(tx, rec, date, exclude_objects)
    colors = family_colors(set(tx["family"].dropna()) | set(rec["family"].dropna()))
    stations = _lanes(rec_d, tx_station)
    ylab = {s: _station_label(s, tx_station, sep="<br>") for s in stations}
    fig = go.Figure()

    def ms(a, b):
        return (b - a).dt.total_seconds() * 1000

    def bars(d, a, b, fill, text, textcolor, hover, pattern=None):
        fig.add_trace(go.Bar(
            base=a, x=ms(a, b), y=[ylab[s] for s in d["station"]], orientation="h",
            marker=dict(color=fill, line=dict(color="white", width=1),
                        pattern=dict(shape=pattern) if pattern else None),
            text=text, textposition="inside", insidetextanchor="middle",
            textfont=dict(color=textcolor, size=11), hovertext=hover, hoverinfo="text",
            showlegend=False))

    # Recordings
    for kind_radar in (True, False):
        d = rec_d[(rec_d["kind"] == "radar") == kind_radar]
        for key, g in d.groupby("family" if kind_radar else "kind"):
            col = colors.get(key, OTHER_COLOR) if kind_radar else OTHER_COLOR
            alpha = RX_ALPHA if kind_radar else 0.5
            a, b = _naive(g["rec_start"]), _naive(g["rec_end"])
            hover = []
            for r in g.itertuples():
                head = f"<b>{r.station}</b> " + (f"{r.tx_id}<br>{r.tx_file}" if kind_radar
                                                 else f"{r.kind}: {r.object}")
                listen = f", {r.listen_s:.0f} s after TX" if pd.notna(r.listen_s) else ""
                files = "<br>".join(Path(p).name for p in str(r.paths).split(" | "))
                hover.append(f"{head}<br>recording {r.duration_s:.0f} s{listen}, "
                             f"{r.n_channels} ch<br>{files}<br>{_fmt_issues(r.issues)}")
            bars(g, a, b, _rgba(col, alpha), None, INK, hover)

    # Transmissions on the transmitting station's lane
    if tx_station in stations:
        d = tx_d[tx_d["tx_end"].notna()].assign(station=tx_station)
        for (fam, est), g in d.groupby(["family", "tx_end_estimated"]):
            a, b = _naive(g["tx_time"]), _naive(g["tx_end"])
            hover = [f"<b>TX {r.tx_id}</b><br>{r.tx_file}<br>"
                     f"{pd.Timestamp(x0):%H:%M:%S}–{pd.Timestamp(x1):%H:%M:%S} UTC"
                     f"{' (end estimated)' if est else f', {r.tx_duration_s:.1f} s'}<br>"
                     f"gain {r.tx_gain}, received by {r.stations}<br>{_fmt_issues(r.issues)}"
                     for r, x0, x1 in zip(g.itertuples(), a, b)]
            bars(g, a, b, colors[fam], None, INK, hover, pattern="/" if est else None)

    # Labels centred on each recording, on top of everything (as in the static
    # version); only where they fit at the initial zoom (~1100 px plot width).
    span = (_naive(rec_d["rec_end"]).max() - _naive(rec_d["rec_start"]).min()).total_seconds()
    px = rec_d["duration_s"] / span * 1100
    text = rec_d["family"].where(rec_d["kind"] == "radar", rec_d["object"]).fillna("")
    fits = (px > 5.8 * text.str.len() + 3) & (text != "")
    d = rec_d[fits]
    mid = _naive(d["rec_start"]) + (_naive(d["rec_end"]) - _naive(d["rec_start"])) / 2
    fig.add_trace(go.Scatter(x=mid, y=[ylab[s] for s in d["station"]], mode="text",
                             text=text[fits], textfont=dict(color=INK, size=11),
                             hoverinfo="skip", showlegend=False))

    fig.update_xaxes(type="date", gridcolor=GRID, tickformat="%H:%M",
                     title_text=f"Time (UTC), {date}")
    fig.update_yaxes(autorange="reversed", categoryorder="array",
                     categoryarray=[ylab[s] for s in stations], showgrid=False, ticks="")
    fig.update_layout(
        title=dict(text=f"Venus radar {date}: {len(tx_d)} transmissions", x=0.01),
        template="plotly_white", barmode="overlay", bargap=0.3,
        height=170 + 60 * len(stations),
        hoverlabel=dict(align="left"), margin=dict(l=10, r=10, t=60, b=10))
    return fig


def main(argv=None):
    ap = argparse.ArgumentParser(description=__doc__,
                                 formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("catalog", type=Path, help="catalog directory (from build_catalog.py)")
    ap.add_argument("date", help="day to plot, e.g. 2026-10-17")
    ap.add_argument("-o", "--out", type=Path, help="save static figure (.pdf, .png, .svg)")
    ap.add_argument("--html", type=Path, help="save interactive figure as standalone HTML")
    ap.add_argument("--width", type=float, default=12, help="static figure width in inches")
    ap.add_argument("--start", help="crop the static figure, e.g. 10:30 (UTC)")
    ap.add_argument("--end", help="crop the static figure, e.g. 13:20 (UTC)")
    args = ap.parse_args(argv)

    tx, rec = load_catalog(args.catalog)
    if args.html:
        timeline_plotly(tx, rec, args.date).write_html(args.html, include_plotlyjs="cdn")
        print(f"written {args.html}")
    if args.out or not args.html:
        fig = timeline_mpl(tx, rec, args.date, width=args.width, start=args.start, end=args.end)
        if args.out:
            fig.savefig(args.out, dpi=200, bbox_inches="tight")
            print(f"written {args.out}")
        else:
            import matplotlib.pyplot as plt
            plt.show()


if __name__ == "__main__":
    main()
