Skip to content

flat_combine

Combine a stack of flat frames into a master flat (raw, not normalised).
Category Master frames
Backend numpy - implemented here on top of numpy primitives
Version 2.0.0
Reads ctx.images (a list of ImageFrame)
Writes extras.master_flat

Pixel-wise median (default) or σ-clipped mean. Normalisation is intentionally NOT folded in: keep flat_combine producing the raw master, then call flat_normalize on the result. Separation of concerns mirrors the bias_combine / dark_combine pattern. Caveat: flat_normalize divides the master by a single global median (not row-by-row / not along the dispersion), so the flat lamp's spectral shape stays imprinted in the normalised flat and is divided into the science frame — the catalogue has no equivalent of IRAF's response (fit of the lamp continuum along the dispersion) yet; for spectrophotometry derive the response with response_from_standard afterwards. v2.0.0 (method='mean' with sigma_clip only): same MAD = 0 fallback as dark_combine v2.0.0 — the σ-clip scale falls back to 1.2533 × the mean absolute deviation about the median instead of rejecting every value ≠ median ([10,10,10,11,12], σ=3: v1 → 10.0, v2 → 10.6; [10,10,10,11,1000] → 10.25, outlier still rejected). method='median' is unchanged.

Parameters

Parameter Default Required Description
method 'median' - 'median' (robust default) or 'mean' (with optional sigma_clip).
bias_key None - ctx.extras key for a master bias to subtract from each frame. None = no pre-subtraction.
dark_key None - ctx.extras key for a master dark to subtract from each frame. None = no pre-subtraction.
scale_by_exptime True - Scale the master dark by EXPTIME_flat / EXPTIME_dark before subtracting. Requires both EXPTIMEs in the headers.
sigma_clip None - σ threshold for σ-clipped mean (method='mean' only). None or ≤0 disables clipping.

Use it

from spectro_kernel import run_algorithm

output = run_algorithm("flat_combine", ctx, {
    "method": "median",
    "bias_key": None,
    "dark_key": None,
    "scale_by_exptime": True,
    "sigma_clip": None
})

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

{
  "tool": "flat_combine",
  "arguments": {
    "session_id": "<session_id>",
    "params": {
      "method": "median",
      "bias_key": null,
      "dark_key": null,
      "scale_by_exptime": true,
      "sigma_clip": null
    }
  }
}

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

References

  • Howell 2006 — Handbook of CCD Astronomy, ch. 4 (CCD reduction).