GrismFLT

class grizli.model.GrismFLT(grism_file='', sci_extn=1, direct_file='', pad=200, ref_file=None, ref_ext=0, seg_file=None, shrink_segimage=True, force_grism='G141', verbose=True, process_jwst_header=True)[source]

Bases: object

Scripts for modeling of individual grism FLT images

Read FLT files and, optionally, reference/segmentation images.

Parameters:
grism_file : str

Grism image (optional). Empty string or filename of a FITS file that must contain extensions (‘SCI’, sci_extn), (‘ERR’, sci_extn), and (‘DQ’, sci_extn). For example, a WFC3/IR “FLT” FITS file.

sci_extn : int

EXTNAME of the file to consider. For WFC3/IR this can only be 1. For ACS and WFC3/UVIS, this can be 1 or 2 to specify the two chips.

direct_file : str

Direct image (optional). Empty string or filename of a FITS file that must contain extensions (‘SCI’, sci_extn), (‘ERR’, sci_extn), and (‘DQ’, sci_extn). For example, a WFC3/IR “FLT” FITS file.

pad : int

Padding to add around the periphery of the images to allow modeling of dispersed spectra for objects that could otherwise fall off of the direct image itself. Modeling them requires an external reference image (ref_file) that covers an area larger than the individual direct image itself (e.g., a mosaic of a survey field).

For WFC3/IR spectra, the first order spectra reach 248 and 195 pixels for G102 and G141, respectively, and pad could be set accordingly if the reference image is large enough.

ref_file : str or ImageHDU/PrimaryHDU

Image mosaic to use as the reference image in place of the direct image itself. For example, this could be the deeper image drizzled from all direct images taken within a single visit or it could be a much deeper/wider image taken separately in perhaps even a different filter.

Note

Assumes that the WCS are aligned between grism_file, direct_file and ref_file!

ref_ext : int

FITS extension to use if ref_file is a filename string.

seg_file : str or ImageHDU/PrimaryHDU

Segmentation image mosaic to associate pixels with discrete objects. This would typically be generated from a rectified image like ref_file, though here it is not required that ref_file and seg_file have the same image dimensions but rather just that the WCS are aligned between them.

shrink_segimage : bool

Try to make a smaller cutout of the reference images to speed up blotting and array copying. This is most helpful for very large input mosaics.

force_grism : str

Use this grism in “simulation mode” where only direct_file is specified.

verbose : bool

Print status messages to the terminal.

Attributes:
grism, direct : ImageData

Grism and direct image data and parameters

conf : aXeConf

Grism configuration object.

seg : array-like

Segmentation image array.

model : array-like

Model of the grism exposure with the same dimensions as the full detector array.

object_dispersers : dict

Container for storing information about what objects have been added to the model of the grism exposure

catalog : Table

Associated photometric catalog. Not required.

Methods Summary

apply_POM([warn_if_too_small, verbose]) Apply pickoff mask to segmentation map to control sources that are dispersed onto the detector
blot_catalog(input_catalog[, columns, …]) Compute detector-frame coordinates of sky positions in a catalog.
compute_full_model([ids, mags, mag_limit, …]) Compute flat-spectrum model for multiple objects.
compute_model_orders([id, x, y, size, mag, …]) Compute dispersed spectrum for a given object id
get_dispersion_PA([decimals]) Compute exact PA of the dispersion axis, including tilt of the trace and the FLT WCS
load_from_fits(save_file) Load saved data from a FITS file
load_photutils_detection([seg_file, …]) Load segmentation image and catalog, either from photutils or SExtractor.
mask_mosaic_edges([sky_poly, verbose, …]) Mask edges of exposures that might not have modeled spectra
old_make_edge_mask([scale, force]) Make a mask for the edge of the grism FoV that isn’t covered by the direct image
photutils_detection([use_seg, data_ext, …]) Use photutils to detect objects and make segmentation map
process_ref_file(ref_file[, ref_ext, …]) Read and blot a reference image
process_seg_file(seg_file[, …]) Read and blot a rectified segmentation image
save_full_pickle([verbose]) Save entire GrismFLT object to a pickle
save_model([overwrite, verbose]) Save model properties to FITS file
save_wcs([overwrite, verbose]) TBD
smooth_mask([gaussian_width, threshold]) Compute a mask where smoothed residuals greater than some value
transform_NIRISS([verbose]) Rotate data & wcs so that spectra are increasing to +x

Methods Documentation

apply_POM(warn_if_too_small=True, verbose=True)[source]

Apply pickoff mask to segmentation map to control sources that are dispersed onto the detector

blot_catalog(input_catalog, columns=['id', 'ra', 'dec'], sextractor=False, ds9=None)[source]

Compute detector-frame coordinates of sky positions in a catalog.

Parameters:
input_catalog : Table

Full catalog with sky coordinates. Can be SExtractor or other.

columns : [str,str,str]

List of columns that specify the object id, R.A. and Decl. For catalogs created with SExtractor this might be [‘NUMBER’, ‘X_WORLD’, ‘Y_WORLD’].

Detector coordinates will be computed with self.direct.wcs.all_world2pix with origin=1.

ds9 : DS9, optional

If provided, load circular regions at the derived detector coordinates.

Returns:
catalog : Table

New catalog with columns ‘x_flt’ and ‘y_flt’ of the detector coordinates. Also will copy the columns names to columns with names ‘id’,’ra’, and ‘dec’ if necessary, e.g., for SExtractor catalogs.

compute_full_model(ids=None, mags=None, mag_limit=22, store=True, verbose=False, size=10, compute_size=True)[source]

Compute flat-spectrum model for multiple objects.

Parameters:
ids : None, list, or array

id numbers to compute in the model. If None then take all ids from unique values in self.seg.

mags : None, float, or list / array

magnitudes corresponding to list if ids. If None, then compute magnitudes based on the flux in segmentation regions and zeropoints determined from PHOTFLAM and PHOTPLAM.

size, compute_size : int, bool

Sizes of individual cutouts, see compute_model_orders.

Returns:
Updated model stored in self.model attribute.
compute_model_orders(id=0, x=None, y=None, size=10, mag=-1, spectrum_1d=None, is_cgs=False, compute_size=False, max_size=None, store=True, in_place=True, get_beams=None, psf_params=None, verbose=True)[source]

Compute dispersed spectrum for a given object id

Parameters:
id : int

Object ID number to match in the segmentation image

x, y : float

Center of the cutout to extract

size : int

Radius of the cutout to extract. The cutout is equivalent to

>>> xc, yc = int(x), int(y)
>>> thumb = self.direct.data['SCI'][yc-size:yc+size, xc-size:xc+size]
mag : float

Specified object magnitude, which will be compared to the “MMAG_EXTRACT_[BEAM]” parameters in self.conf to decide if the object is bright enough to compute the higher spectral orders. Default of -1 means compute all orders listed in self.conf.beams

spectrum_1d : None or [array, array]

Template 1D spectrum to convolve with the grism disperser. If None, assumes trivial spectrum flat in f_lambda flux densities. Otherwise, the template is taken to be

>>> wavelength, flux = spectrum_1d
is_cgs : bool

Flux units of spectrum_1d[1] are cgs f_lambda flux densities, rather than normalized in the detection band.

compute_size : bool

Ignore x, y, and size and compute the extent of the segmentation polygon directly using utils_c.disperse.compute_segmentation_limits.

max_size : int or None

Enforce a maximum size of the cutout when using compute_size.

store : bool

If True, then store the computed beams in the OrderedDict self.object_dispersers[id].

If many objects are computed, this can be memory intensive. To save memory, set to False and then the function just stores the input template spectrum (spectrum_1d) and the beams will have to be recomputed if necessary.

in_place : bool

If True, add the computed spectral orders into self.model. Otherwise, make a clean array with only the orders of the given object.

get_beams : list or None

Spectral orders to retrieve with names as defined in the configuration files, e.g., [‘A’] generally for the +1st order of HST grisms. If None, then get all orders listed in the beams attribute of the aXeConf configuration object.

psf_params : list

Optional parameters for generating an EffectivePSF object for the spatial morphology.

Returns:
output : bool or numpy.array

If in_place is True, return status of True if everything goes OK. The computed spectral orders are stored in place in self.model.

Returns False if the specified id is not found in the segmentation array independent of in_place.

If in_place is False, return a full array including the model for the single object.

get_dispersion_PA(decimals=0)[source]

Compute exact PA of the dispersion axis, including tilt of the trace and the FLT WCS

Parameters:
decimals : int or None

Number of decimal places to round to, passed to round. If None, then don’t round.

Returns:
dispersion_PA : float

PA (angle East of North) of the dispersion axis.

load_from_fits(save_file)[source]

Load saved data from a FITS file

Parameters:
save_file : str

Filename of the saved output

Returns:
True if completed successfully
load_photutils_detection(seg_file=None, seg_cat=None, catalog_format='ascii.commented_header')[source]

Load segmentation image and catalog, either from photutils or SExtractor.

If SExtractor, use catalog_format='ascii.sextractor'.

mask_mosaic_edges(sky_poly=None, verbose=True, force=False, err_scale=10, dq_mask=False, dq_value=1024, resid_sn=7)[source]

Mask edges of exposures that might not have modeled spectra

old_make_edge_mask(scale=3, force=False)[source]

Make a mask for the edge of the grism FoV that isn’t covered by the direct image

Parameters:
scale : float

Scale factor to multiply to the mask before it’s applied to the self.grism.data['ERR'] array.

force : bool

Force apply the mask even if self.has_edge_mask is set indicating that the function has already been run.

Returns:
Nothing, updates self.grism.data['ERR'] in place.
Sets self.has_edge_mask = True.
photutils_detection(use_seg=False, data_ext='SCI', detect_thresh=2.0, grow_seg=5, gauss_fwhm=2.0, verbose=True, save_detection=False, ZP=None)[source]

Use photutils to detect objects and make segmentation map

Parameters:
detect_thresh : float

Detection threshold, in sigma

grow_seg : int

Number of pixels to grow around the perimeter of detected objects witha maximum filter

gauss_fwhm : float

FWHM of Gaussian convolution kernel that smoothes the detection image.

verbose : bool

Print logging information to the terminal

save_detection : bool

Save the detection images and catalogs

ZP : float or None

AB magnitude zeropoint of the science array. If None then, try to compute based on PHOTFLAM and PHOTPLAM values and use zero if that fails.

Returns:
status : bool

True if completed successfully. False if data_ext=='REF' but no reference image found.

Stores an astropy.table.Table object to self.catalog and a
segmentation array to self.seg.
process_ref_file(ref_file, ref_ext=0, shrink_segimage=True, verbose=True)[source]

Read and blot a reference image

Parameters:
ref_file : str or ImageHDU / PrimaryHDU

Filename or astropy.io.fits Image HDU of the reference image.

shrink_segimage : bool

Try to make a smaller cutout of the reference image to speed up blotting and array copying. This is most helpful for very large input mosaics.

verbose : bool

Print some status information to the terminal

Returns:
status : bool

False if ref_file is None. True if completes successfully.

The blotted reference image is stored in the array attribute
self.direct.data['REF'].
The ref_filter attribute is determined from the image header and the
ref_photflam scaling is taken either from the header if possible, or
the global photflam variable defined at the top of this file.
process_seg_file(seg_file, shrink_segimage=True, verbose=True)[source]

Read and blot a rectified segmentation image

Parameters:
seg_file : str or ImageHDU / PrimaryHDU

Filename or astropy.io.fits Image HDU of the segmentation image.

shrink_segimage : bool

Try to make a smaller cutout of the segmentation image to speed up blotting and array copying. This is most helpful for very large input mosaics.

verbose : bool

Print some status information to the terminal

Returns:
The blotted segmentation image is stored in the attribute GrismFLT.seg.
save_full_pickle(verbose=True)[source]

Save entire GrismFLT object to a pickle

save_model(overwrite=True, verbose=True)[source]

Save model properties to FITS file

save_wcs(overwrite=True, verbose=True)[source]

TBD

smooth_mask(gaussian_width=4, threshold=2.5)[source]

Compute a mask where smoothed residuals greater than some value

Perhaps useful for flagging contaminated pixels that aren’t in the model, such as high orders dispersed from objects that fall off of the direct image, but this hasn’t yet been extensively tested.

Parameters:
gaussian_width : float

Width of the Gaussian filter used with gaussian_filter.

threshold : float

Threshold, in sigma, above which to flag residuals.

Returns:
Nothing, but pixels are masked in self.grism.data['SCI'].
transform_NIRISS(verbose=True)[source]

Rotate data & wcs so that spectra are increasing to +x