Stage 2 — Data Introduction (PSF Ground-Test Dataset)¶

df_first_sample = pd.read_csv(DATA_DIR / "rgs000_0_first.csv")
print("rgs000_0_first.csv", df_first_sample.shape)
print(df_first_sample.columns.tolist())
df_first_sample.head()

df_zeroth_sample = pd.read_csv(DATA_DIR / "rgs000_0_zeroth.csv")
print("rgs000_0_zeroth.csv", df_zeroth_sample.shape)
print(df_zeroth_sample.columns.tolist())
df_zeroth_sample.head()

# Sanity check: row counts before/after the sig_max quality filter, per config.
first_datasets = {}
for config in CONFIGS:
    raw = pd.read_csv(DATA_DIR / f"{config}_first.csv")
    filtered = load_spectra(DATA_DIR / f"{config}_first.csv")
    first_datasets[config] = filtered
    print(f"{config:12s} raw={len(raw):6d}  filtered={len(filtered):6d}  "
          f"spectra={filtered['spectra_id'].nunique()}")

def plot_field(df, title=""):
    """Scatter unique source positions in telescope-simulator angle space."""
    unique = df.drop_duplicates(subset="spectra_id")
    fig, ax = plt.subplots(figsize=(5, 5))
    ax.scatter(unique["theta"], unique["phi"], s=10)
    ax.set_xlabel("theta [deg]")
    ax.set_ylabel("phi [deg]")
    ax.set_aspect("equal")
    ax.set_title(title)
    plt.show()


plot_field(first_datasets["rgs000_0"], title="rgs000_0 -- field coverage")

def plot_centroids(df, color_by="wavelength", title=""):
    """Scatter PSF centroids in the detector mosaic frame R_MOS."""
    fig, ax = plt.subplots(figsize=(6, 5))
    sc = ax.scatter(df["cent_y"], df["cent_z"], c=df[color_by], cmap="rainbow", s=5)
    fig.colorbar(sc, ax=ax, label=color_by)
    ax.set_xlabel("cent_y [mm]")
    ax.set_ylabel("cent_z [mm]")
    ax.set_title(title)
    plt.show()


plot_centroids(first_datasets["rgs000_0"], title="rgs000_0 -- centroids in R_MOS")

def compare_gwa(configs, labels):
    """Overlay median centroids across GWA settings to show the GWA-induced shift.

    Sources are not paired 1:1 across configs (separate exposures), so the
    reported shift is a population-mean estimate, not a per-source delta.
    """
    fig, ax = plt.subplots(figsize=(6, 5))
    means = {}
    for config, label in zip(configs, labels):
        med = median_per_spectrum(load_spectra(DATA_DIR / f"{config}_first.csv"))
        ax.scatter(med["cent_y"], med["cent_z"], s=5, alpha=0.5, label=label)
        means[label] = (med["cent_y"].mean(), med["cent_z"].mean())
    ax.set_xlabel("cent_y [mm]")
    ax.set_ylabel("cent_z [mm]")
    ax.legend()
    ax.set_title("GWA angle comparison")
    plt.show()

    ref_label = labels[0]
    ref_y, ref_z = means[ref_label]
    for label in labels[1:]:
        y, z = means[label]
        print(f"{label} vs {ref_label}: mean shift dy={y - ref_y:+.3f} mm, "
              f"dz={z - ref_z:+.3f} mm")


compare_gwa(["rgs000_0", "rgs000_m4", "rgs000_p4"], ["nominal", "-4 deg", "+4 deg"])

def compare_orders(config):
    """Overlay 1st- and 0th-order centroids for one config.

    1st- and 0th-order rows for the same config share spectra_id (same
    source exposure), so per-spectrum separation can be computed directly.
    """
    first = median_per_spectrum(load_spectra(DATA_DIR / f"{config}_first.csv"))
    zeroth = zeroth_order_centers(DATA_DIR / f"{config}_zeroth.csv")
    merged = first.merge(zeroth, on="spectra_id", suffixes=("_1st", "_0th"))

    fig, ax = plt.subplots(figsize=(6, 5))
    ax.scatter(first["cent_y"], first["cent_z"], s=5, alpha=0.4, label="1st order")
    ax.scatter(zeroth["cent_y"], zeroth["cent_z"], s=20, color="black", label="0th order")
    ax.set_xlabel("cent_y [mm]")
    ax.set_ylabel("cent_z [mm]")
    ax.legend()
    ax.set_title(f"Order comparison -- {config}")
    plt.show()

    sep = np.hypot(merged["cent_y_1st"] - merged["cent_y_0th"],
                    merged["cent_z_1st"] - merged["cent_z_0th"])
    print(f"{config}: mean 1st/0th-order separation = {sep.mean():.3f} mm "
          f"(n={len(merged)} matched lines)")


compare_orders("rgs000_0")

def plot_spectra(df, title=""):
    """Final view: dispersed centroids in R_MOS colored by wavelength."""
    plot_centroids(df, color_by="wavelength", title=title)


plot_spectra(first_datasets["rgs000_0"], title="rgs000_0 -- spectra in R_MOS")