gelsa.specframe#

Classes

SpecFrame([continuum_subtraction])

Represents a spectral frame (observation) in the Gelsa simulation.

class gelsa.specframe.SpecFrame(continuum_subtraction=None, **kwargs)[source]#

Bases: object

Represents a spectral frame (observation) in the Gelsa simulation.

This class handles the parameters, loading, and coordinate transformations for a specific spectral observation frame (e.g., a NISP slitless spectroscopy exposure). It interfaces with various calibration models (detector, optical, dispersion, sensitivity, PSF) to provide accurate coordinate conversions and flux calculations. It can load existing FITS frames or be used to define and simulate new ones.

load_frame(frame_path=None, loctable_path=None, persistence_path=None)[source]#

Load frame data and metadata from a FITS file.

Reads the primary header and potentially updates pointing information (RA, DEC, PA) either from specific SIR headers or by using a location table if provided or found automatically.

Parameters:

frame_path (str, optional) – Path to the FITS science frame file. Can be .gz compressed. Defaults to None.
loctable_path (str, optional) – Path to the corresponding location table FITS file. If None, attempts to find it automatically based on the science frame path. Defaults to None.

property hdul#

Access the FITS HDUList object for the frame.

Loads the FITS file on first access if not already loaded.

Returns:: The HDUList object.
Return type:: astropy.io.fits.HDUList

close_frame()[source]#

Close the associated FITS file handle.

Deletes internal references to the HDUList and header. Closing a frame that is already closed does nothing.

set_detector_model(detector_model)[source]#

Set the detector model for coordinate transformations.

Parameters:: detector_model (detector_model.DetectorModel) – The detector model instance.

set_optical_model(optical_model)[source]#

Set the optical model based on the current grism and tilt.

Parameters:: optical_model (optical_model.OpticalModel) – The optical model instance.

set_dispersion_model(dispersion_model)[source]#

Set the dispersion models (IDS and CRV) based on grism and tilt.

Parameters:: dispersion_model (dict) – A dictionary containing ‘ids’ and ‘crv’ DisplacementModel instances.

set_sensitivity(sensitivity_model)[source]#

Set the sensitivity model and update the frame’s wavelength range.

Parameters:: sensitivity_model (sensitivity_model.SensitivityModel) – The sensitivity model instance.

set_relative_flux_model(relative_flux_model)[source]#

Set the relative flux loss calibration model.

Parameters:: relative_flux_model (relative_flux.RelativeFluxCalibration or None) – The relative flux model instance, or None if not used.

set_psf_model(psf_model)[source]#

Set the Point Spread Function (PSF) model.

Parameters:: psf_model (psf_model.PSFModel or psf_model.DefaultPSFModel or None) – The PSF model instance, or None if not used.

set_zero_order_mask(zero_order_mask)[source]#

Set and apply the zero-order contamination mask.

Parameters:: zero_order_mask (zero_order_mask.ZeroOrderMask or None) – The zero-order mask instance, or None if not used.

property detector_shape#

Return detector size in pixels (ny, nx).

Note the order (ny, nx) consistent with numpy array indexing.

Returns:: (height, width) in pixels.
Return type:: tuple

arcsec_to_pixel(x_arcsec)[source]#

Convert units from arsec to pixels

x_pix = x_arcsec / pixscale with pixscale in arcsec/pixel

radec_to_pixel_(ra, dec, wavelength, dispersion_order=1, **kwargs)[source]#

Compute detector pixel coordinates from RA, Dec sky position and wavelength.

Parameters:

ra (float or numpy.ndarray) – Sky position RA in degrees.
dec (float or numpy.ndarray) – Sky position Dec in degrees.
wavelength (float or numpy.ndarray) – Wavelength in angstrom.
dispersion_order (int, optional) – Dispersion order (0 or 1). Defaults to 1.
**kwargs – Additional arguments passed to framecoord.radec_to_pixel.

Returns:

(x, y, detector_index): x (float or ndarray): Pixel x-coordinate(s). y (float or ndarray): Pixel y-coordinate(s). detector_index (int or ndarray): Detector index/indices (0-15), -1 if off detector.

Return type:

tuple

radec_to_pixel(ra, dec, wavelength, dispersion_order=1, **kwargs)[source]#

Compute detector pixel coordinates from RA, Dec sky position and wavelength.

Parameters:

ra (float or numpy.ndarray) – Sky position RA in degrees.
dec (float or numpy.ndarray) – Sky position Dec in degrees.
wavelength (float or numpy.ndarray) – Wavelength in angstrom.
dispersion_order (int, optional) – Dispersion order (0 or 1). Defaults to 1.
**kwargs – Additional arguments passed to framecoord.radec_to_pixel.

Returns:

(x, y, detector_index): x (float or ndarray): Pixel x-coordinate(s). y (float or ndarray): Pixel y-coordinate(s). detector_index (int or ndarray): Detector index/indices (0-15), -1 if off detector.

Return type:

tuple

radec_to_fov(ra, dec, wavelength, dispersion_order=1, **kwargs)[source]#

Compute detector pixel coordinates from RA, Dec sky position and wavelength.

Parameters:

ra (float or numpy.ndarray) – Sky position RA in degrees.
dec (float or numpy.ndarray) – Sky position Dec in degrees.
wavelength (float or numpy.ndarray) – Wavelength in angstrom.
dispersion_order (int, optional) – Dispersion order (0 or 1). Defaults to 1.
**kwargs – Additional arguments passed to framecoord.radec_to_pixel.

Returns:

(x, y, detector_index): x (float or ndarray): Pixel x-coordinate(s). y (float or ndarray): Pixel y-coordinate(s). detector_index (int or ndarray): Detector index/indices (0-15), -1 if off detector.

Return type:

tuple

fov_to_pixel(xfov, yfov, **kwargs)[source]#

Compute detector pixel coordinates from RA, Dec sky position and wavelength.

Parameters:

ra (float or numpy.ndarray) – Sky position RA in degrees.
dec (float or numpy.ndarray) – Sky position Dec in degrees.
wavelength (float or numpy.ndarray) – Wavelength in angstrom.
dispersion_order (int, optional) – Dispersion order (0 or 1). Defaults to 1.
**kwargs – Additional arguments passed to framecoord.radec_to_pixel.

Returns:

(x, y, detector_index): x (float or ndarray): Pixel x-coordinate(s). y (float or ndarray): Pixel y-coordinate(s). detector_index (int or ndarray): Detector index/indices (0-15), -1 if off detector.

Return type:

tuple

pixel_to_radec(x, y, det, wavelength, dispersion_order=1)[source]#

Compute sky position RA, Dec from detector pixel coordinates and wavelength.

Parameters:

x (float or numpy.ndarray) – Detector pixel x-coordinate(s).
y (float or numpy.ndarray) – Detector pixel y-coordinate(s).
det (int or numpy.ndarray) – NISP detector index/indices (0-15).
wavelength (float or numpy.ndarray) – Wavelength in angstrom.
dispersion_order (int, optional) – Dispersion order (0 or 1). Defaults to 1.

Returns:

(RA, Dec): RA (float or ndarray): Right Ascension coordinate(s) in degrees. Dec (float or ndarray): Declination coordinate(s) in degrees.

Return type:

tuple

sample_psf(x=None, y=None, detector=None, wavelength_ang=None, **args)[source]#

Draw samples representing the PSF offset at given coordinates/wavelength.

Parameters:

x (float or ndarray, optional) – Detector x-coordinate(s). Not currently used for position dependence. Defaults to None.
y (float or ndarray, optional) – Detector y-coordinate(s). Not currently used for position dependence. Defaults to None.
detector (int or ndarray, optional) – Detector index/indices. Not currently used. Defaults to None.
wavelength_ang (float or ndarray, optional) – Wavelength(s) in angstroms. Used for chromatic PSF. Defaults to None.
**args – Additional arguments passed to psf_model.sample_psf.

Returns:

(dx, dy) offsets in pixel coordinates, or (0, 0) if no PSF model is set.

Return type:

tuple

lineflux_to_counts(flux, wavelength)[source]#

Convert line flux in erg/s/cm^2 to photon counts.

Uses the sensitivity model and exposure time.

Parameters:

flux (float or ndarray) – Line flux in erg/s/cm^2.
wavelength (float or ndarray) – Wavelength(s) in angstroms.

Returns:

Corresponding photon counts.

Return type:

float or ndarray

flux_to_counts(flux, wavelength)[source]#

Convert flux density in erg/s/cm^2/A to photon counts.

Uses the sensitivity model, wavelength step, and exposure time.

Parameters:

flux (float or ndarray) – Flux density in erg/s/cm^2/A.
wavelength (float or ndarray) – Wavelength array in angstroms. Assumes uniform spacing to calculate step.

Returns:

Corresponding photon counts.

Return type:

float or ndarray

counts_to_flux(counts, wavelength)[source]#

Convert photon counts to flux density in erg/s/cm^2/A.

Inverse of flux_to_counts. Uses sensitivity, wavelength step, and exposure time.

Parameters:

counts (float or ndarray) – Photon counts.
wavelength (float or ndarray) – Wavelength array in angstroms. Assumes uniform spacing to calculate step.

Returns:

Corresponding flux density in erg/s/cm^2/A.

Return type:

float or ndarray

get_sensitivity(wavelength)[source]#

Return sensitivity (response) in units counts/(erg/cm^2/s).

Note: This is the sensitivity integrated over the pixel wavelength step.

Parameters:: wavelength (float or ndarray) – Wavelength array in angstroms. Assumes uniform spacing to calculate step.
Returns:: Sensitivity value(s).
Return type:: float or ndarray

sensitivity(wavelength)#

Return sensitivity (response) in units counts/(erg/cm^2/s).

Note: This is the sensitivity integrated over the pixel wavelength step.

Parameters:: wavelength (float or ndarray) – Wavelength array in angstroms. Assumes uniform spacing to calculate step.
Returns:: Sensitivity value(s).
Return type:: float or ndarray

get_relative_flux_loss_radec(ra, dec, wavelength_ang=None)[source]#

Calculates the relative flux loss factor at given detector coordinates and wavelength.

Uses the relative flux calibration model (relative_flux_loss_params) if it has been set via set_relative_flux_model.

Parameters:

x (float | np.ndarray) – Detector x-coordinate(s).
y (float | np.ndarray) – Detector y-coordinate(s).
det_index (int | np.ndarray) – NISP detector index/indices (0-15).
wavelength_ang (float | np.ndarray) – Wavelength(s) in Angstroms.

Returns:

Flux loss factor. This is a multiplicative factor: (<= 1.0) representing the fraction of flux remaining after accounting for effects like vignetting or detector gaps modeled by the relative flux calibration. Returns 1.0 if no model is set or if the model doesn’t apply to the given inputs. The shape matches the input coordinate/wavelength arrays.

Return type:

float | np.ndarray

Raises:

AttributeError – If the detector model has not been set (needed by the underlying relative_flux.get_flux_loss).

get_detector(detector_index)[source]#

Get the pixel data arrays for a specific detector.

Retrieves the science image, data quality (mask), and variance arrays. Applies the zero-order mask if it has been set.

Parameters:

detector_index (int) – NISP detector index (0-15).

Returns:

(image, mask, variance): image (ndarray): Science image data. mask (ndarray): Data quality mask (0=good, 1=bad). variance (ndarray): Variance data.

Return type:

tuple

cutout(ra, dec, redshift=0, lam_step=20, wavelength_range=None, select_detector=None, **crop_args)[source]#

Create spectral cutouts (SpecCrop objects) around a sky position.

Calculates the trace of the object across the detectors for the given wavelength range and creates SpecCrop instances for each detector the trace falls on.

Parameters:

ra (float) – Right Ascension of the target center (degrees).
dec (float) – Declination of the target center (degrees).
redshift (float, optional) – Redshift of the target (used for metadata). Defaults to 0.
lam_step (float, optional) – Wavelength step for calculating the trace (Angstroms). Defaults to 20.
wavelength_range (tuple, optional) – (min, max) wavelength range for the trace. Defaults to the frame’s sensitivity range.
**crop_args – Additional keyword arguments passed to SpecCrop.crop_trace (e.g., padx, pady for padding around the trace).

Returns:

A dictionary where keys are detector indices (int) and values: are the corresponding SpecCrop objects.

Return type:

dict

Raises:

ValueError – If the target’s trace does not fall on any detector within the specified wavelength range.

add_sources(galaxy_list, **kwargs)[source]#

Simulate and add sources to the frame’s internal data arrays.

This method is used when the SpecFrame is not loaded from an existing FITS file but is being used for simulation. It uses SpectralImager to generate the image of the provided galaxies.

Parameters:

galaxy_list (list) – A list of Galaxy objects to simulate.
**kwargs – Additional keyword arguments passed to SpectralImager.make_image.

resample_on_wavelength(ra, dec, **args)[source]#

Extracts and combines 2D spectra onto a uniform wavelength grid.

Creates cutouts around the target RA/Dec using cutout, then calls resample_on_wavelength on each SpecCrop object. The results from all detectors are summed.

Parameters:

ra (float) – Right Ascension of the target center (degrees).
dec (float) – Declination of the target center (degrees).
**args – Additional keyword arguments passed directly to SpecCrop.resample_on_wavelength (e.g., wave_range, wave_step, extraction_window, ndrops).

Returns:

im (np.ndarray): The combined, resampled 2D spectrum (flux).
var (np.ndarray): The combined variance of the resampled spectrum.
norm (np.ndarray): The combined normalization map (sum of weights).
pix_bins (tuple): The pixel and wavelength bin edges used for resampling, taken from the last processed crop (assumes they are consistent).

Return type:

tuple

Raises:

ValueError – If cutout fails to find the target on any detector.
# Add other potential exceptions from SpecCrop.resample_on_wavelength –