build.py

import os
import pandas as pd
import numpy as np
import plotly.graph_objects as go
from plotly.subplots import make_subplots

# -----------------------------
# Config
# -----------------------------
DATA_FILE = os.path.join("data", "HadCRUT.4.6.0.0.monthly_ns_avg.txt")
OUT_HTML = "index.html"

# Spiral geometry (tweakable)
R_OFFSET = 1.2          # shifts anomalies to positive radii
R_SCALE = 1.0           # extra scaling if you want bigger/smaller spiral
Z_SCALE = 0.04          # vertical spacing between years (helix height)

# Visual settings
BG_COLOR_FIG = "#323331"
BG_COLOR_PLOT = "#000100"
GRID_COLOR = "rgba(255,255,255,0.15)"
FAINT_OPACITY = 0.18
FAINT_WIDTH = 1.2
HILITE_WIDTH = 6.0

MONTHS = ["Jan","Feb","Mar","Apr","May","Jun",
          "Jul","Aug","Sep","Oct","Nov","Dec"]

# -----------------------------
# 1) Load + prepare HadCRUT
# -----------------------------
if not os.path.exists(DATA_FILE):
    raise FileNotFoundError(f"Missing data file: {DATA_FILE}")

# File format: first col "YYYY/MM", second col anomaly in °C
raw = pd.read_csv(DATA_FILE, delim_whitespace=True, usecols=[0, 1], header=None)
raw.columns = ["ym", "value"]

raw["year"] = raw["ym"].astype(str).str.split("/").str[0].astype(int)
raw["month"] = raw["ym"].astype(str).str.split("/").str[1].astype(int)
df = raw[["year", "month", "value"]].copy()

# keep full years (12 months)
counts = df.groupby("year")["month"].count()
full_years = counts[counts == 12].index
df = df[df["year"].isin(full_years)].reset_index(drop=True)

# baseline mean 1850–1900
baseline = df.loc[(df["year"] >= 1850) & (df["year"] <= 1900), "value"].mean()
df["anomaly"] = df["value"] - baseline

years = np.sort(df["year"].unique())
year_min, year_max = int(years.min()), int(years.max())

# Annual mean anomalies for bottom chart
annual = df.groupby("year")["anomaly"].mean().reset_index()

# Save cleaned data (for reproducibility / “store the data”)
os.makedirs("data", exist_ok=True)
df.to_csv(os.path.join("data", "hadcrut_monthly_clean.csv"), index=False)
annual.to_csv(os.path.join("data", "hadcrut_annual_mean.csv"), index=False)

# -----------------------------
# 2) Build 3D helix coordinates
# -----------------------------
# Angles: Jan at the top, months clockwise in x-y plane
angles = (np.pi / 2) - (2 * np.pi) * ((df["month"] - 1) / 12.0)

# radius = anomaly shifted positive
r = (df["anomaly"] + R_OFFSET) * R_SCALE

df["x"] = r * np.cos(angles)
df["y"] = r * np.sin(angles)
df["z"] = (df["year"] - year_min) * Z_SCALE   # vertical axis = time

# Color mapping by annual mean (we pass the scalar, Plotly handles colorscale)
year_means = annual.set_index("year")["anomaly"]
def year_color(val):
    return val  # we give scalar; colorscale defined in layout/trace

# -----------------------------
# 3) Figure layout: 3D (top) + time series (bottom)
# -----------------------------
fig = make_subplots(
    rows=2, cols=1,
    specs=[[{"type": "scene"}], [{"type": "xy"}]],
    row_heights=[0.72, 0.28],
    vertical_spacing=0.06
)

# --- Static faint helix lines for ALL years ---
for yr in years:
    d = df[df["year"] == yr].sort_values("month")
    xs = np.r_[d["x"].values, d["x"].values[0]]
    ys = np.r_[d["y"].values, d["y"].values[0]]
    zs = np.r_[d["z"].values, d["z"].values[0]]

    fig.add_trace(
        go.Scatter3d(
            x=xs, y=ys, z=zs,
            mode="lines",
            line=dict(
                width=FAINT_WIDTH,
                color=year_color(year_means.loc[yr]),
                colorscale="RdBu_r",
                cmin=year_means.min(),
                cmax=year_means.max(),
            ),
            opacity=FAINT_OPACITY,
            showlegend=False,
            hoverinfo="skip",
        ),
        row=1, col=1
    )

# --- Bottom: static faint full time series line (context) ---
fig.add_trace(
    go.Scatter(
        x=annual["year"],
        y=annual["anomaly"],
        mode="lines",
        line=dict(width=2, color="rgba(255,255,255,0.25)"),
        hoverinfo="skip",
        showlegend=False
    ),
    row=2, col=1
)

# --- Bottom: animated growing line (initially at first year only) ---
yr0 = int(years[0])
initial_sub = annual[annual["year"] <= yr0]
fig.add_trace(
    go.Scatter(
        x=initial_sub["year"],
        y=initial_sub["anomaly"],
        mode="lines",
        line=dict(width=3, color="rgba(255,255,255,0.95)"),
        hovertemplate="Year %{x}<br>Anomaly %{y:.2f}°C<extra></extra>",
        showlegend=False
    ),
    row=2, col=1
)

# --- 3D highlighted spiral (will be updated by frames) ---
d0 = df[df["year"] == yr0].sort_values("month")
xs0 = np.r_[d0["x"].values, d0["x"].values[0]]
ys0 = np.r_[d0["y"].values, d0["y"].values[0]]
zs0 = np.r_[d0["z"].values, d0["z"].values[0]]

highlight_trace_3d = go.Scatter3d(
    x=xs0, y=ys0, z=zs0,
    mode="lines",
    line=dict(
        width=HILITE_WIDTH,
        color=year_color(year_means.loc[yr0]),
        colorscale="RdBu_r",
        cmin=year_means.min(),
        cmax=year_means.max(),
    ),
    opacity=1.0,
    name="Selected year",
    showlegend=False,
    hovertemplate=(
        "Year: %{customdata[0]}<br>"
        "Month: %{customdata[1]}<br>"
        "Anomaly: %{customdata[2]:.2f}°C<extra></extra>"
    ),
    customdata=np.zeros((len(xs0), 3)),
)

fig.add_trace(highlight_trace_3d, row=1, col=1)

# --- Bottom: moving marker on the time series ---
marker_trace = go.Scatter(
    x=[yr0],
    y=[float(annual.loc[annual["year"] == yr0, "anomaly"].iloc[0])],
    mode="markers+text",
    marker=dict(size=12, color="rgba(255,255,255,0.95)"),
    text=[str(yr0)],
    textposition="top center",
    textfont=dict(color="white", size=16),
    hovertemplate="Year %{x}<br>Anomaly %{y:.2f}°C<extra></extra>",
    showlegend=False
)
fig.add_trace(marker_trace, row=2, col=1)

# Trace indices (important for frames)
# 0 .. len(years)-1      -> faint 3D lines
# len(years)             -> static faint time-series line
# len(years)+1           -> growing time-series line (animated)
# len(years)+2           -> highlighted 3D spiral (animated)
# len(years)+3           -> marker on time series (animated)

# -----------------------------
# 4) Build frames (one per year)
# -----------------------------
frames = []

for yr in years:
    # --- 3D highlighted spiral for this year ---
    d = df[df["year"] == yr].sort_values("month")
    xs = np.r_[d["x"].values, d["x"].values[0]]
    ys = np.r_[d["y"].values, d["y"].values[0]]
    zs = np.r_[d["z"].values, d["z"].values[0]]

    month_labels = [MONTHS[m-1] for m in d["month"].values]
    month_labels = month_labels + [month_labels[0]]
    anomalies = np.r_[d["anomaly"].values, d["anomaly"].values[0]]

    customdata = np.column_stack([
        np.full(len(xs), int(yr)),
        np.array(month_labels, dtype=object),
        anomalies
    ])

    # --- Bottom chart data up to current year ---
    sub = annual[annual["year"] <= yr]
    y_anom = sub.iloc[-1]["anomaly"]

    frames.append(
        go.Frame(
            name=str(int(yr)),
            data=[
                # 3D highlighted spiral
                go.Scatter3d(
                    x=xs, y=ys, z=zs,
                    line=dict(
                        width=HILITE_WIDTH,
                        color=year_color(year_means.loc[yr]),
                        colorscale="RdBu_r",
                        cmin=year_means.min(),
                        cmax=year_means.max(),
                    ),
                    customdata=customdata,
                ),
                # Growing line on time series
                go.Scatter(
                    x=sub["year"],
                    y=sub["anomaly"],
                ),
                # Moving marker
                go.Scatter(
                    x=[int(yr)],
                    y=[y_anom],
                    text=[str(int(yr))],
                ),
            ],
            traces=[
                len(years) + 2,  # highlighted 3D spiral
                len(years) + 1,  # growing line
                len(years) + 3,  # marker
            ],
        )
    )

fig.frames = frames

# -----------------------------
# 5) Slider + play button
# -----------------------------
slider_steps = [
    dict(
        method="animate",
        args=[[str(int(yr))],
              dict(mode="immediate", frame=dict(duration=0, redraw=True),
                   transition=dict(duration=0))],
        label=str(int(yr))
    )
    for yr in years
]

fig.update_layout(
    updatemenus=[
        dict(
            type="buttons",
            showactive=False,
            x=0.02, y=1.02,
            xanchor="left", yanchor="bottom",
            buttons=[
                dict(
                    label="Play",
                    method="animate",
                    args=[None,
                          dict(frame=dict(duration=60, redraw=True),
                               transition=dict(duration=0),
                               fromcurrent=True,
                               mode="immediate")]
                ),
                dict(
                    label="Pause",
                    method="animate",
                    args=[[None],
                          dict(frame=dict(duration=0, redraw=False),
                               mode="immediate",
                               transition=dict(duration=0))]
                ),
            ],
        )
    ],
    sliders=[
        dict(
            active=0,
            currentvalue=dict(prefix="Year: ", font=dict(color="white", size=16)),
            pad=dict(t=30),
            x=0.08, y=0.98,
            len=0.84,
            font=dict(color="white"),
            steps=slider_steps
        )
    ]
)

# -----------------------------
# 6) Styling + axes
# -----------------------------
fig.update_layout(
    title=dict(
        text=f"Global Temperature Change ({year_min}–{year_max})",
        x=0.5,
        xanchor="center",
        font=dict(color="white", size=26)
    ),
    paper_bgcolor=BG_COLOR_FIG,
    plot_bgcolor=BG_COLOR_PLOT,
    margin=dict(l=20, r=20, t=90, b=30),
)

fig.update_scenes(
    row=1, col=1,
    bgcolor=BG_COLOR_PLOT,
    xaxis=dict(
        showbackground=False,
        showgrid=True, gridcolor=GRID_COLOR,
        zeroline=False,
        showticklabels=False,
        title=""
    ),
    yaxis=dict(
        showbackground=False,
        showgrid=True, gridcolor=GRID_COLOR,
        zeroline=False,
        showticklabels=False,
        title=""
    ),
    zaxis=dict(
        showbackground=False,
        showgrid=False,
        zeroline=False,
        showticklabels=False,
        title=""
    ),
    camera=dict(
        eye=dict(x=1.8, y=1.2, z=0.8)
    )
)

fig.update_xaxes(
    row=2, col=1,
    showgrid=False,
    zeroline=False,
    tickfont=dict(color="white"),
    title="",
)
fig.update_yaxes(
    row=2, col=1,
    showgrid=True,
    gridcolor="rgba(255,255,255,0.08)",
    zeroline=False,
    tickfont=dict(color="white"),
    title="Anomaly (°C)",
)

# Annotation for baseline
fig.add_annotation(
    text="Baseline: 1850–1900 mean (HadCRUT4)",
    xref="paper", yref="paper",
    x=0.01, y=0.02,
    showarrow=False,
    font=dict(color="rgba(255,255,255,0.6)", size=12)
)

# -----------------------------
# 7) Write standalone HTML
# -----------------------------
fig.write_html(OUT_HTML, include_plotlyjs=True, full_html=True)
print(f"Wrote {OUT_HTML} (open it in a browser).")
print("Saved cleaned data:")
print(" - data/hadcrut_monthly_clean.csv")
print(" - data/hadcrut_annual_mean.csv")