dispcraft.measurement¶

def load_spectra(filepath, sig_max=0.05, sig_columns=("sig_y", "sig_z")):
    """Load a PSF dataset and drop rows with uncertain centroids.

    Parameters
    ----------
    filepath : str or Path -- path to a *_first.csv or *_zeroth.csv file
    sig_max : float -- centroid uncertainty threshold [mm]; rows with
        any column in `sig_columns` at or above this are dropped as low
        quality.
    sig_columns : tuple of str -- which uncertainty columns to filter on.
        Defaults to both axes (first-order data has both). 0th-order data
        only has `sig_y` populated -- `e_PSF_centroid[1]` (sig_z) is never
        measured for it, so callers of zeroth data must pass
        `sig_columns=("sig_y",)` or every row is dropped (NaN < sig_max is
        always False).

    Returns
    -------
    pd.DataFrame -- filtered rows, index reset.
    """
    df = pd.read_csv(filepath)
    mask = pd.Series(True, index=df.index)
    for col in sig_columns:
        mask &= df[col] < sig_max
    return df[mask].reset_index(drop=True)

def median_per_spectrum(df):
    """Collapse repeated centroid measurements to one row per (spectrum, line).

    Parameters
    ----------
    df : pd.DataFrame -- a *_first.csv-shaped DataFrame (e.g. from load_spectra)

    Returns
    -------
    pd.DataFrame -- one median row per (spectra_id, wavelength) pair.
    """
    return df.groupby(["spectra_id", "wavelength"]).median().reset_index()

def zeroth_order_centers(filepath, sig_max=0.05):
    """Compute one 0th-order center per spectrum from the two-blob model.

    Each spectrum has a rank-1 (blue edge, 1206 nm) and rank-2 (red edge,
    1892 nm) blob -- the RGS passband's transmission edges, per
    doi:10.1051/0004-6361/202555859 (not the previous round-number
    placeholders) -- the 0th-order center is their mean centroid.

    Parameters
    ----------
    filepath : str or Path -- path to a *_zeroth.csv file
    sig_max : float -- centroid uncertainty threshold [mm], see load_spectra.

    Returns
    -------
    pd.DataFrame -- one row per spectra_id with cent_y, cent_z, theta, phi.
    """
    df = _median_per_rank(load_spectra(filepath, sig_max=sig_max, sig_columns=("sig_y",)))
    centers = df.groupby("spectra_id").agg(
        cent_y=("cent_y", "mean"),
        cent_z=("cent_z", "mean"),
        theta=("theta", "first"),
        phi=("phi", "first"),
    ).reset_index()
    return centers

def zeroth_order_separation(filepath, sig_max=0.05):
    """Per-spectrum rank2-rank1 (red-blue) 0th-order two-blob separation.

    The physical model's `m=0` grating term predicts zero wavelength
    dependence for the 0th order, but this separation is measurably
    non-zero and field-position-dependent (Stage 5 Phase 3) -- an
    unmodeled chromatic effect, not noise. Step 4 found the *prism*'s own
    chromatic dispersion (unaffected by `m`) explains part of it -- see
    `dispcraft.zeroth_dispersion.predict_zeroth_order_separation_physical`.

    Parameters
    ----------
    filepath : str or Path -- path to a *_zeroth.csv file
    sig_max : float -- centroid uncertainty threshold [mm], see load_spectra.

    Returns
    -------
    pd.DataFrame -- one row per spectra_id with both ranks present:
        spectra_id, dy, dz (mm), y_nisp, z_nisp (rank-1's field position).
    """
    df = _median_per_rank(load_spectra(filepath, sig_max=sig_max, sig_columns=("sig_y",)))
    piv_y = df.pivot_table(index="spectra_id", columns="rank", values="cent_y")
    piv_z = df.pivot_table(index="spectra_id", columns="rank", values="cent_z")
    pos = df[df["rank"] == 1].set_index("spectra_id")[["y_nisp", "z_nisp"]]
    out = pd.DataFrame({"dy": piv_y[2] - piv_y[1], "dz": piv_z[2] - piv_z[1]}).dropna().join(pos)
    return out.reset_index()