Instrument API#

Instrument-specific configuration: header conversion, readout settings, and fibre-table management. Currently supports the ISOPLANE spectrograph. See the Isoplane theory for instrument details.

Header conversion utilities for KSPEC data.

This module provides functions to convert raw headers from various instruments (e.g., PIXIS/Isoplane backup CCD) to the standard format required by kspecdr.

kspecdr.inst.isoplane.add_fiber_table(hdul: HDUList, n_fibers: int, fiber_table: Table | None = None) → None[source]#

Add a dummy fiber table to the HDUList.

Parameters:

  • hdul (fits.HDUList) – The FITS HDUList to modify in place.

  • n_fibers (int) – Number of fibers to include in the table.

  • fiber_table (Table, optional) – Fiber table to add to the HDUList. If None, a dummy fiber table will be created.

kspecdr.inst.isoplane.convert_isoplane_header(header: Header, ndfclass: str) → Header[source]#

Convert a PIXIS/Isoplane raw header to the standard kspecdr format.

Parameters:

  • header (fits.Header) – The original raw header.

  • ndfclass (str) – The NDFCLASS of the data (e.g., “MFOBJECT”, “MFARC”, “MFFFF”, “BIAS”, “DARK”).

Returns:

The converted header with standardized keywords.

Return type:

fits.Header

kspecdr.inst.isoplane.get_isoplane_readout_settings(header: Header) → dict[source]#

Determine readout gain/noise from raw header.

Returns:

Mapping with keys gain, noise, speed_mhz, gain_mode, and noise_mode.

Return type:

dict

kspecdr.inst.isoplane.sanitize_header_drop_unparsable(hdr: Header, max_passes: int = 50, verbose: bool = True) → Header[source]#

Return a cleaned copy of hdr by removing any cards that raise VerifyError (or ValueError) when converted to a FITS card image (str(card)). Also removes associated CONTINUE chains.

This is meant for headers that contain broken OGIP long-string CONTINUE blocks.

Parameters:

  • hdr (fits.Header)

  • max_passes (int) – Safety limit to avoid infinite loops.

  • verbose (bool) – Print which cards were dropped.

Returns:

Cleaned header.

Return type:

fits.Header

kspecdr.inst.isoplane.write_isoplane_converted_image(fpath: str, output_fpath: str, ndfclass: str, n_fibers: int | None = None, fiber_table: Table | None = None, split_frames: bool = False) → List[str] | None[source]#

Convert a PIXIS/Isoplane raw FITS file into a kspecdr-compatible file.

This reads the input header, applies standard keyword conversions, attaches a fiber table, normalizes the data to a single 2D frame, applies requested orientation flips, and writes the result to a new FITS file.

Parameters:

  • fpath (str) – Input raw FITS filename.

  • output_fpath (str) – Output converted FITS filename.

  • ndfclass (str) – NDFCLASS to stamp into the converted header.

  • n_fibers (int, optional) – Number of fibers to create when using a dummy fiber table.

  • fiber_table (astropy.table.Table, optional) – Fiber table to attach; if provided, this is used instead of a dummy table.

  • split_frames (bool, optional) – If True and the input is a 3D cube with multiple frames, write each frame to a separate file by appending a 4-digit index to output_fpath.

Returns:

List of output paths when split_frames is True and multiple frames exist; otherwise None.

Return type:

list of str or None