Interface functions for IFU jitter observation processing. More...

Functions
cpl_error_code	eris_ifu_stdstar_fill_common_parameterlist (const char recipeName, jitterModes jitterMode, cpl_parameterlist pl)
	Fill parameter list with standard star-specific parameters.

cpl_error_code	eris_ifu_jitter_fill_extract_parameterlist (char context, jitterModes jitterMode, cpl_parameterlist pl)
	Fill parameter list with source extraction parameters.

cpl_error_code	eris_ifu_jitter_fill_common_parameterlist (const char recipeName, jitterModes jitterMode, cpl_parameterlist pl)
	Fill parameter list with common jitter recipe parameters.

cpl_error_code	eris_ifu_jitter_fetch_params (const char context, const char recipe_name, const cpl_parameterlist parlist, struct stdParamStruct stdParams, struct paramStruct *params)
	Fetch and parse jitter recipe parameters from parameter list.

cpl_error_code	eris_ifu_jitter_processSof (cpl_frameset frames, struct stdParamStruct stdParams, struct paramStruct params, struct sofStruct sof)
	Process SOF (Set of Frames) file and load all calibration data.

cpl_error_code	eris_ifu_jitter_get_instrument_settings (cpl_frameset frames, ifsInstrument instrument, ifsBand band, ifsPreopticsScale scale)
	Extract instrument configuration from frameset.

cpl_error_code	eris_ifu_jitter_get_objsky_exposures (cpl_frameset frames, struct stdParamStruct params, struct sofStruct sof)
	Load all object and sky exposures from frameset.

Detailed Description

Interface functions for IFU jitter observation processing.

This module provides the infrastructure for processing jittered IFU observations, including parameter management, SOF (Set of Frames) processing, and data reduction workflows for science, standard star, PSF, and pupil observations.

Key functionality includes:

Recipe parameter list creation and population for various observation modes
SOF file parsing and validation
Calibration file loading (dark, flat, distortion, wavelength maps)
Object-sky frame pairing based on temporal proximity
Instrument configuration extraction
Support for efficiency computation, response calibration, and flux calibration
Differential Atmospheric Refraction (DAR) correction
Sky subtraction methods for automatic jitter observations
Data cube resampling with multiple interpolation methods

The module supports multiple observation modes:

Science observations (M_SCIENCE)
Standard star observations for efficiency/response (M_STD, M_TELLURIC)
PSF observations for Strehl ratio computation
Pupil lamp observations

Function Documentation

◆ eris_ifu_jitter_fetch_params()

cpl_error_code eris_ifu_jitter_fetch_params	(	const char *	context,
		const char *	recipe_name,
		const cpl_parameterlist *	parlist,
		struct stdParamStruct *	stdParams,
		struct paramStruct *	params
	)

Fetch and parse jitter recipe parameters from parameter list.

Parameters

context	Recipe context string (e.g., "eris.recipename")
recipe_name	Recipe name for standard parameter extraction
parlist	Input parameter list to read from
stdParams	Output structure for standard parameters (modified in place)
params	Output structure for jitter-specific parameters (modified in place)

Returns: CPL_ERROR_NONE on success, otherwise an error code

Note

This function extracts all recipe parameters from the CPL parameter list and populates the stdParams and params structures. Parameters include:

Standard pipeline parameters (via eris_ifu_fetch_std_param)
Sky tweaking and OH alignment settings
Thermal background subtraction
Velocity offset and BPM threshold
Cube construction parameters
Extraction and DAR correction settings
Derotator correction
Bad pixel correction iterations

String parameters are parsed and converted to appropriate types (e.g., stretch_resampling: "linear" -> LINEAR, "spline" -> SPLINE)

The derot_corr parameter accepts "auto" (converted to NaN) or numeric values

Uses TRY/CATCH error handling for robustness

Definition at line 1059 of file eris_ifu_jitter_interface.c.

References BRK_WITH_ERROR_MSG, CATCH, CHECK_ERROR_STATE, eris_check_error_code(), eris_ifu_fetch_std_param(), and TRY.

Referenced by eris_stdstar_reduction_common().

◆ eris_ifu_jitter_fill_common_parameterlist()

cpl_error_code eris_ifu_jitter_fill_common_parameterlist	(	const char *	recipeName,
		jitterModes	jitterMode,
		cpl_parameterlist *	pl
	)

Fill parameter list with common jitter recipe parameters.

Parameters

recipeName	Recipe name for parameter context (e.g., "stdstar", "jitter")
jitterMode	Observation mode (M_SCIENCE, M_STD, M_PSF, M_PUPIL, M_TELLURIC)
pl	Parameter list to populate (modified in place)

Returns: CPL_ERROR_NONE on success, otherwise an error code

Note

This is the main parameter creation function for jitter recipes. It creates comprehensive parameter lists including:

Standard parameters (via eris_ifu_add_std_params)
Sky tweaking and OH alignment parameters
Thermal background subtraction
Velocity offset correction for wavelength scale
Bad pixel map threshold
Cube construction parameters (slitlet detection, fine-tuning)
Resampling parameters (via eris_ifu_jitter_fill_resample_parameterlist)
Background subtraction
Field margin and edge trimming
Extraction parameters (via eris_ifu_jitter_fill_extract_parameterlist)
Flux calibration
DAR correction (via eris_ifu_jitter_fill_dar_parameterlist)
Derotator correction
Automatic jitter parameters (sky estimation methods, for jitter recipes only)
Phase 3 product creation (for jitter recipes only)
Bad pixel correction iterations
NaN plane removal

For jitter recipes (when recipeName contains "jitter"), additional parameters for automatic sky estimation are created, including 8 different methods for computing sky from object frames when sky frames are missing

Uses TRY/CATCH error handling to ensure proper cleanup on failure

Definition at line 648 of file eris_ifu_jitter_interface.c.

References CATCH, CHECK_ERROR_STATE, eris_check_error_code(), eris_ifu_add_std_params(), eris_ifu_free_string(), eris_ifu_jitter_fill_extract_parameterlist(), and TRY.

◆ eris_ifu_jitter_fill_extract_parameterlist()

cpl_error_code eris_ifu_jitter_fill_extract_parameterlist	(	char *	context,
		jitterModes	jitterMode,
		cpl_parameterlist *	pl
	)

Fill parameter list with source extraction parameters.

Parameters

context	Recipe context string (e.g., "eris.recipename")
jitterMode	Observation mode (affects default values)
pl	Parameter list to populate (modified in place)

Returns: CPL_ERROR_NONE on success, otherwise an error code

Note

Creates parameters for point source extraction including:

extract-source: Enable/disable point source extraction (default: TRUE for STD/PSF, FALSE for SCIENCE/PUPIL)
mask_method: Method to specify extraction mask (mask, position, max, fit, or optimal)
center: Center coordinates of circular extraction mask in pixels (e.g., "32,32")
radius: Radius of circular extraction mask in pixels (default: 4.0, or 11.0 for stdstar)

The extraction parameters are used to extract spectra from specific spatial regions in the data cube, particularly for standard stars and PSF calibrators

This function is called by eris_ifu_jitter_fill_common_parameterlist()

Definition at line 550 of file eris_ifu_jitter_interface.c.

References eris_check_error_code().

Referenced by eris_ifu_jitter_fill_common_parameterlist().

◆ eris_ifu_jitter_get_instrument_settings()

cpl_error_code eris_ifu_jitter_get_instrument_settings	(	cpl_frameset *	frames,
		ifsInstrument *	instrument,
		ifsBand *	band,
		ifsPreopticsScale *	scale
	)

Extract instrument configuration from frameset.

Parameters

frames	Input frameset containing raw data frames
instrument	Output instrument type (SPIFFIER or SPIFFI) (modified in place)
band	Output observing band (J/H/K variants) (modified in place)
scale	Output pre-optics scale (modified in place)

Returns: CPL_ERROR_NONE on success, CPL_ERROR_DATA_NOT_FOUND if no raw frames found

Note

This function searches the frameset for the first RAW frame and extracts instrument configuration from its FITS header, including:

Instrument type (SPIFFIER vs SPIFFI)
Observing band (J_LOW, J_SHORT, H_LOW, K_MIDDLE, etc.)
Pre-optics scale setting

The function stops after finding the first RAW frame, assuming all raw frames in the SOF have consistent instrument settings

Returns error if no RAW frames are found in the frameset

Definition at line 1574 of file eris_ifu_jitter_interface.c.

References CATCH, CHECK_ERROR_STATE, eris_check_error_code(), eris_ifu_get_band(), eris_ifu_get_instrument_frame(), eris_ifu_get_preopticsScale(), SET_ERROR_MSG, and TRY.

Referenced by eris_ifu_jitter_processSof().

◆ eris_ifu_jitter_get_objsky_exposures()

cpl_error_code eris_ifu_jitter_get_objsky_exposures	(	cpl_frameset *	frames,
		struct stdParamStruct	params,
		struct sofStruct *	sof
	)

Load all object and sky exposures from frameset.

Parameters

frames	Input frameset containing raw object and sky frames
params	Standard parameters structure (contains raw image correction mask)
sof	SOF structure to populate with exposure data (modified in place)

Returns: CPL_ERROR_NONE on success, otherwise an error code

Note

This function:

Allocates exposure table to hold all object and sky frames
Iterates through frameset identifying object and sky frames by tag
Determines observation mode (SCIENCE, STD, STD_FLUX, PSF, PUPIL) from tags
Loads each exposure using eris_ifu_load_exposure_frame()
Extracts observation metadata (DIT, MJD-OBS, altitude, rotation)
Computes automatic derotation correction
Creates and combines bad pixel masks
Optionally saves debug products if productDepth >= PD_DEBUG

Recognized object tags: OBJ, STD, STD_FLUX, PSF, PUPIL_LAMP, PUPIL_SKY

Recognized sky tags: SKY, OBJ_SKY, STD_SKY, STD_FLUX_SKY, PSF_SKY, PUPIL_SKY

All frames in the SOF must have consistent observation mode (no mixing SCIENCE with STD, etc.), except for generic SKY frames (IGNORE_SOF_MODE)

Memory for raw images, DQI images, and bad pixel masks is allocated and stored in sof->exposureTable[]

Returns error if no object frames found or if mixed observation modes detected

Definition at line 1666 of file eris_ifu_jitter_interface.c.

References BRK_WITH_ERROR_MSG, CATCH, eris_check_error_code(), eris_ifu_free_string(), eris_ifu_get_dit(), eris_ifu_load_exposure_frame(), eris_ifu_save_hdrl_image_dbg(), hdrl_image_get_mask(), hdrl_image_reject_from_mask(), and TRY.

Referenced by eris_ifu_jitter_processSof().

◆ eris_ifu_jitter_processSof()

cpl_error_code eris_ifu_jitter_processSof	(	cpl_frameset *	frames,
		struct stdParamStruct	stdParams,
		struct paramStruct	params,
		struct sofStruct *	sof
	)

Process SOF (Set of Frames) file and load all calibration data.

Parameters

frames	Input frameset containing all raw and calibration files
stdParams	Standard parameters structure
params	Jitter-specific parameters structure
sof	Output SOF structure to populate (modified in place)

Returns: CPL_ERROR_NONE on success, otherwise an error code

Note

This is the main SOF processing function that:

Validates frameset and sets frame groups via eris_ifu_dfs_set_groups()
Extracts instrument settings (band, scale, instrument type)
Creates detector quality image (DQI)
Loads calibration frames:
- Bad pixel maps (dark, flat, detlin)
- Master dark frame
- Master flat field
- Distortion polynomials (old or new format)
- Slitlet distances and positions
- Wavelength calibration map
- OH reference spectrum (optional)
Combines all bad pixel masks into master BPM
Loads all object and sky exposures via eris_ifu_jitter_get_objsky_exposures()
Pairs object frames with closest sky frames via eris_ifu_jitter_get_objsky_pairs()

The function supports both old distortion format (poly_u, poly_v, distances, positions) and new format (distortion polynomials array, borders)

OH reference spectrum is band-specific (J/H/K/HK) and used for wavelength alignment

Memory for all loaded calibration data is allocated and stored in the sof structure

Uses TRY/CATCH error handling with comprehensive error messages

Warning: Requires sufficient memory to load all raw exposures and calibration data

Definition at line 1264 of file eris_ifu_jitter_interface.c.

References BRK_IF_NULL, BRK_WITH_ERROR_MSG, CATCH, CHECK_ERROR_STATE, eris_check_error_code(), eris_ifu_dfs_set_groups(), eris_ifu_get_bandString(), eris_ifu_jitter_get_instrument_settings(), eris_ifu_jitter_get_objsky_exposures(), eris_ifu_lcorr_get_peak_lambdas(), eris_ifu_lcorr_read_OH_reference_spectrum(), eris_ifu_load_cal_image_frame(), eris_ifu_load_distances(), eris_ifu_load_distortion_polynomials(), eris_ifu_load_distortion_polynomials_old(), eris_ifu_load_slit_positions(), eris_ifu_quality2bp_mask(), and TRY.

Referenced by eris_stdstar_reduction_common().

◆ eris_ifu_stdstar_fill_common_parameterlist()

cpl_error_code eris_ifu_stdstar_fill_common_parameterlist	(	const char *	recipeName,
		jitterModes	jitterMode,
		cpl_parameterlist *	pl
	)

Fill parameter list with standard star-specific parameters.

Parameters

recipeName	Recipe name for parameter context (e.g., "stdstar")
jitterMode	Observation mode (M_SCIENCE, M_STD, M_TELLURIC, etc.)
pl	Parameter list to populate (modified in place)

Returns: CPL_ERROR_NONE on success, otherwise an error code

Note

Creates parameters for:

Efficiency computation from standard star spectrum
Response computation from standard star spectrum
Strehl ratio computation from PSF star
PSF flux integration and background radii
Response polynomial fitting parameters (degree, kappa-sigma clipping)

Parameters are added with recipe-specific context prefix "eris.<recipeName>." and CLI aliases for command-line access

Default values may vary based on jitterMode (e.g., M_SCIENCE disables efficiency/response computation by default)

Definition at line 97 of file eris_ifu_jitter_interface.c.

References eris_check_error_code(), and eris_ifu_free_string().

Functions

Detailed Description

Function Documentation

◆ eris_ifu_jitter_fetch_params()

◆ eris_ifu_jitter_fill_common_parameterlist()

◆ eris_ifu_jitter_fill_extract_parameterlist()

◆ eris_ifu_jitter_get_instrument_settings()

◆ eris_ifu_jitter_get_objsky_exposures()

◆ eris_ifu_jitter_processSof()

◆ eris_ifu_stdstar_fill_common_parameterlist()