Skip to content

subtract_bias

Subtract the master bias, a constant level, or the pedestal of the frame's margin.
Category Preprocessing (2-D image)
Backend numpy - implemented here on top of numpy primitives
Version 1.1.0
Reads ctx.image (an ImageFrame)
Writes image, metrics.bias_median, metrics.median_after, metrics.n_negative, metrics.n_clipped, metrics.applied, metrics.n_reference_columns, metrics.residual_adu

Native counterpart of subtract_bias_easyspec: the same arithmetic without the easyspec staging (no temporary FITS, no clipping unless clip_negative is set), so integer-ADU frames and BZERO-scaled files are handled in float64 end to end. Precedence: an explicit bias_level wins, then overscan_columns, then overscan_auto, then the master frame stored in ctx.extras[bias_key] ; with none available the brick fails. When an overscan option is used the master frame is never read. Negative pixels are kept by default because clipping biases the sky statistics of faint frames ; clip_negative=True reproduces the easyspec pad_with_zeros behaviour. v1.1.0 — margin pedestal: the reference columns are the explicit [lo, hi) range or the columns of unilluminated_columns(detection_sigma, guard_columns) ; the pedestal is astropy's sigma_clipped_stats mean (clip_sigma) over every pixel of those columns, the residual after subtraction is measured the same way. Fewer than min_columns reference columns (auto mode: the spectrum reaches both detector edges, no reference) or a pedestal above max_level_adu go to on_invalid: 'fail' or 'skip' (applied = 0, frame untouched). Metrics in those modes: bias_median (the pedestal), median_after, n_negative, n_clipped, applied, n_reference_columns, residual_adu ; meta bias_source 'margin' (auto) or 'overscan' (explicit). The master-frame and bias_level paths are byte-identical to 1.0.0. Companion of dark_subtract (which scales by exposure time) and flat_normalize.

Parameters

Parameter Default Required Description
bias_key 'master_bias' - Key in ctx.extras where the master bias (an ImageFrame) is stored.
bias_level None - Constant bias level in ADU to subtract instead of a master frame (e.g. the overscan mean); takes precedence over every other source when set.
clip_negative False - Set the pixels that become negative after subtraction to zero.
overscan_auto False - Measure the pedestal on the columns the spectrum never reaches (unilluminated_columns) instead of a master frame.
overscan_columns None - Explicit [lo, hi) range of reference columns (0-based, hi exclusive); takes precedence over overscan_auto and the master frame.
detection_sigma 5.0 - Auto mode: a column is lit when its profile rises this many noise sigmas above the floor (never a fraction of the peak, so a bright line cannot hide a faint continuum).
guard_columns 30 - Auto mode: widen the lit span by this many columns on each side.
min_columns 50 - Auto mode: fewer reference columns than this goes to on_invalid.
clip_sigma 4.0 - Sigma of the clipped mean that estimates the pedestal and the residual.
max_level_adu None - A pedestal above this goes to on_invalid; null means no bound.
on_invalid 'fail' - 'fail' (default) or 'skip' (applied = 0, frame untouched).

Use it

from spectro_kernel import run_algorithm

output = run_algorithm("subtract_bias", ctx, {
    "bias_key": "master_bias",
    "bias_level": None,
    "clip_negative": False,
    "overscan_auto": False,
    "overscan_columns": None,
    "detection_sigma": 5.0,
    "guard_columns": 30,
    "min_columns": 50,
    "clip_sigma": 4.0,
    "max_level_adu": None,
    "on_invalid": "fail"
})

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": "subtract_bias",
  "arguments": {
    "session_id": "<session_id>",
    "params": {
      "bias_key": "master_bias",
      "bias_level": null,
      "clip_negative": false,
      "overscan_auto": false,
      "overscan_columns": null,
      "detection_sigma": 5.0,
      "guard_columns": 30,
      "min_columns": 50,
      "clip_sigma": 4.0,
      "max_level_adu": null,
      "on_invalid": "fail"
    }
  }
}

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, 2nd ed., ch. 4 (bias frames, zero level, overscan and unilluminated regions as the bias reference).
  • Massey 1997 — A User's Guide to CCD Reductions with IRAF (NOAO), zero-level correction.