Skip to content

flat_normalize_response

Flat-field a 2-D spectral frame with a flat normalised along the dispersion.
Category Preprocessing (2-D image)
Backend scipy - implemented here on top of scipy primitives
Version 1.0.0
Reads ctx.image (an ImageFrame)
Writes image, metrics.applied, metrics.science_pedestal_adu, metrics.lit_col_lo, metrics.lit_col_hi, metrics.lit_rows, metrics.corrected_fraction, metrics.pixel_response_std, metrics.illumination_p5, metrics.illumination_p95

N(y, x) = (flat − pedestal) / S(x), S the lamp spectrum (median of the lit rows, median-filtered over smooth_px columns then Gaussian-smoothed with σ = smooth_px / 6), scaled to median 1 over the lit area ; the flat's pedestal is the master bias at bias_key when present, else the median of its darkest 5 % of columns. Pixels outside the lit area, or whose response falls outside [min_response, max_response], get N = 1 and are left untouched. The science frame is corrected as (image − p) / N + p : with pedestal_mode = 'dark_margin' and no master bias on the context, p is the sigma-clipped mean (clip_sigma) of the science pixels in the columns the lamp never reaches on pedestal_side of the lit span (at least min_pedestal_columns of them), so a pedestal still in the frame is not multiplied by the flat pattern and a later margin-pedestal subtraction still finds it ; otherwise p = 0. Metrics: applied, science_pedestal_adu, lit_col_lo / lit_col_hi (first lit column and last lit column + 1, −1 when none), lit_rows, corrected_fraction, pixel_response_std (scatter of N over a 15-column running mean, the pixel-to-pixel part), illumination_p5 / illumination_p95 (5th and 95th percentiles of the row medians of N over the lit columns, the slit-illumination part ; a row with one unusable lit pixel has no median and the percentiles fall back to 1.0 when no row survives). Header FLATCOR = True. Companion: flat_normalize divides by the flat over one global median and keeps the lamp shape ; use it for imaging-like flats, this brick for spectroscopic ones.

Parameters

Parameter Default Required Description
flat_key 'master_flat' - ctx.extras key of the raw master flat (ImageFrame).
bias_key 'master_bias' - ctx.extras key of the master bias subtracted from the flat ; absent, the flat's darkest columns give its pedestal.
smooth_px 51 - Running-median window (columns) of the lamp spectrum ; larger keeps more column-to-column response in N. At least 3.
min_signal_fraction 0.25 - Columns (and rows) where the lamp is below this fraction of its peak are not corrected.
min_response 0.2 - Pixels whose normalised response is below this are not corrected.
max_response 5.0 - Pixels whose normalised response is above this are not corrected.
pedestal_mode 'none' - 'none': divide the frame as it is ; 'dark_margin': hold the science pedestal out of the division, measured on the unlit columns (only when no master bias is on the context).
pedestal_side 'both' - Which unlit columns measure the science pedestal: 'low' (below the lit span), 'high' (above it) or 'both'.
min_pedestal_columns 10 - Fewer unlit columns than this and the pedestal stays 0.
clip_sigma 4.0 - Sigma of the clipped mean that measures the science pedestal.

Use it

from spectro_kernel import run_algorithm

output = run_algorithm("flat_normalize_response", ctx, {
    "flat_key": "master_flat",
    "bias_key": "master_bias",
    "smooth_px": 51,
    "min_signal_fraction": 0.25,
    "min_response": 0.2,
    "max_response": 5.0,
    "pedestal_mode": "none",
    "pedestal_side": "both",
    "min_pedestal_columns": 10,
    "clip_sigma": 4.0
})

The CLI loads a single 1-D spectrum with --input; this algorithm needs ctx.image (an ImageFrame). Run it from Python or as a step of a pipeline preset.

{
  "tool": "flat_normalize_response",
  "arguments": {
    "session_id": "<session_id>",
    "params": {
      "flat_key": "master_flat",
      "bias_key": "master_bias",
      "smooth_px": 51,
      "min_signal_fraction": 0.25,
      "min_response": 0.2,
      "max_response": 5.0,
      "pedestal_mode": "none",
      "pedestal_side": "both",
      "min_pedestal_columns": 10,
      "clip_sigma": 4.0
    }
  }
}

Every algorithm is an MCP tool of the same name; describe_algorithm returns this page's metadata as JSON.

References

  • Massey, Valdes & Barnes 1992 — A User's Guide to Reducing Slit Spectra with IRAF, NOAO (the response normalisation of spectroscopic flats).
  • Howell 2006 — Handbook of CCD Astronomy, 2nd ed., ch. 4 (bias out before the flat division).