ResampleImage

class jwst.resample.resample.ResampleImage(input_models, pixfrac=1.0, kernel='square', fillval='NAN', weight_type='ivm', good_bits=0, blendheaders=True, output_wcs=None, wcs_pars=None, output=None, enable_ctx=True, enable_var=True, report_var=True, compute_err=None, asn_id=None)

Bases: Resample

Resample imaging data.

Initialize the ResampleImage object.

Parameters:

input_modelsModelLibrary

A ModelLibrary-based object allowing iterating over all contained models of interest.

pixfracfloat, optional

The fraction of a pixel that the pixel flux is confined to. The default value of 1 has the pixel flux evenly spread across the image. A value of 0.5 confines it to half a pixel in the linear dimension, so the flux is confined to a quarter of the pixel area when the square kernel is used.

kernel{“square”, “gaussian”, “point”, “turbo”, “lanczos2”, “lanczos3”}, optional

The name of the kernel used to combine the input. The choice of kernel controls the distribution of flux over the kernel. The square kernel is the default.

Warning

The “gaussian” and “lanczos2/3” kernels DO NOT conserve flux.

fillvalfloat, None, str, optional

The value of output pixels that did not have contributions from input images’ pixels. When fillval is either None or "INDEF" and out_img is provided, the values of out_img will not be modified. When fillval is either None or "INDEF" and out_img is not provided, the values of out_img will be initialized to numpy.nan. If fillval is a string that can be converted to a number, then the output pixels with no contributions from input images will be set to this fillval value.

weight_type{“exptime”, “ivm”}, optional

The weighting type for adding models’ data. For weight_type="ivm" (the default), the weighting will be determined per-pixel using the inverse of the read noise (VAR_RNOISE) array stored in each input image. If the VAR_RNOISE array does not exist, the variance is set to 1 for all pixels (i.e., equal weighting). If weight_type="exptime", the weight will be set equal to the measurement time when available and to the exposure time otherwise.

good_bitsint, str, None, optional

An integer bit mask, None, a Python list of bit flags, a comma-, or '|'-separated, '+'-separated string list of integer bit flags or mnemonic flag names that indicate what bits in models’ DQ bitfield array should be ignored (i.e., zeroed).

When co-adding models using add_model(), any pixels with a non-zero DQ values are assigned a weight of zero and therefore they do not contribute to the output (resampled) data. good_bits provides a mean to ignore some of the DQ bitflags.

When good_bits is an integer, it must be the sum of all the DQ bit values from the input model’s DQ array that should be considered “good” (or ignored). For example, if pixels in the DQ array can be combinations of 1, 2, 4, and 8 flags and one wants to consider DQ “defects” having flags 2 and 4 as being acceptable, then good_bits should be set to 2+4=6. Then a pixel with DQ values 2,4, or 6 will be considered a good pixel, while a pixel with DQ value, e.g., 1+2=3, 4+8=12, etc. will be flagged as a “bad” pixel.

Alternatively, when good_bits is a string, it can be a comma-separated or ‘+’ separated list of integer bit flags that should be summed to obtain the final “good” bits. For example, both “4,8” and “4+8” are equivalent to integer good_bits=12.

Finally, instead of integers, good_bits can be a string of comma-separated mnemonics. For example, for JWST, all the following specifications are equivalent:

"12" == "4+8" == "4, 8" == "JUMP_DET, DROPOUT"

In order to “translate” mnemonic code to integer bit flags, Resample.dq_flag_name_map attribute must be set to either a dictionary (with keys being mnemonc codes and the values being integer flags) or a BitFlagNameMap.

In order to reverse the meaning of the flags from indicating values of the “good” DQ flags to indicating the “bad” DQ flags, prepend ‘~’ to the string value. For example, in order to exclude pixels with DQ flags 4 and 8 for computations and to consider as “good” all other pixels (regardless of their DQ flag), use a value of ~4+8, or ~4,8. A string value of ~0 would be equivalent to a setting of None.

Default value (0) will make all pixels with non-zero DQ values be considered “bad” pixels, and the corresponding data pixels will be assigned zero weight and thus these pixels will not contribute to the output resampled data array.

Set good_bits to None to turn off the use of model’s DQ array.

For more details, see documentation for astropy.nddata.bitmask.extend_bit_flag_map.

blendheadersbool, optional

Indicates whether to blend metadata from all input models and store the combined result to the output model.

output_wcsdict, None, optional

Specifies output WCS as a dictionary with keys 'wcs' (WCS object) and 'pixel_scale' (pixel scale in arcseconds). 'pixel_scale', when provided, will be used for computation of drizzle scaling factor. When it is not provided, output pixel scale will be estimated from the provided WCS object. output_wcs object is required when output_model is None. output_wcs is ignored when output_model is provided.

wcs_parsdict, None, optional

A dictionary of custom WCS parameters used to define an output WCS from input models’ outlines. This argument is ignored when output_wcs is specified.

List of supported parameters (keywords in the dictionary):

• pixel_scale_ratio : float

  Desired pixel scale ratio defined as the ratio of the desired output pixel scale to the first input model’s pixel scale computed from this model’s WCS at the fiducial point (taken as the ref_ra and ref_dec from the wcsinfo meta attribute of the first input image). Ignored when pixel_scale is specified. Default value is 1.0.

• pixel_scale : float, None

  Desired pixel scale (in arcsec) of the output WCS. When provided, overrides pixel_scale_ratio. Default value is None.

• output_shape : tuple of two integers (int, int), None

  Shape of the image (data array) using np.ndarray convention (ny first and nx second). This value will be assigned to pixel_shape and array_shape properties of the returned WCS object. Default value is None.

• rotation : float, None

  Position angle of output image’s Y-axis relative to North. A value of 0.0 would orient the final output image to be North up. The default of None specifies that the images will not be rotated, but will instead be resampled in the default orientation for the camera with the x and y axes of the resampled image corresponding approximately to the detector axes. Ignored when transform is provided. Default value is None.

• crpix : tuple of float, None

  Position of the reference pixel in the resampled image array. If crpix is not specified, it will be set to the center of the bounding box of the returned WCS object. Default value is None.

• crval : tuple of float, None

  Right ascension and declination of the reference pixel. Automatically computed if not provided. Default value is None.

outputstr, None, optional

Filename for the output model.

enable_ctxbool, optional

Indicates whether to create a context image. If disable_ctx is set to True, parameters out_ctx, begin_ctx_id, and max_ctx_id will be ignored.

enable_varbool, optional

Indicates whether to resample variance arrays.

report_varbool, optional

Indicates whether to report variance arrays in the output model. In order to get an error array when compute_err=from_var, enable_var must be True, but sometimes it’s useful not to save var_rnoise, var_flat, and var_poisson arrays to decrease output file size.

compute_err{“from_var”, “driz_err”}, None, optional

• "from_var": compute output model’s error array from all (Poisson, flat, readout) resampled variance arrays. Setting compute_err to "from_var" will assume enable_var was set to True regardless of actual value of the parameter enable_var.

• "driz_err": compute output model’s error array by drizzling together all input models’ error arrays.

Error array will be assigned to 'err' key of the output model.

Note

At this time, output error array is not equivalent to error propagation results.

asn_idstr, None, optional

The association id. The id is what appears in the Association Naming.

Attributes Summary

dq_flag_name_map

Methods Summary

add_model(model)	Add a single input model to the resampling.
create_output_jwst_model([ref_input_model])	Create a new blank model and update its meta with info from ref_input_model.
finalize()	Perform final computations and set output model values and metadata.
input_model_to_dict(model, weight_type, ...)	Convert a data model to a dictionary of keywords and values expected by stcal.resample.
resample_group(indices)	Resample multiple input images belonging to a single group_id.
resample_many_to_many([in_memory])	Resample many inputs to many outputs where outputs have a common frame.
resample_many_to_one()	Resample and coadd many inputs to a single output.
reset_arrays([n_input_models])	Initialize/reset between finalize() and add_model() calls.
update_fits_wcsinfo(model)	Update FITS WCS keywords of the resampled image.
update_output_model(model, info_dict)	Add meta information to the output model.

Attributes Documentation

dq_flag_name_map = {'ADJ_OPEN': 134217728, 'AD_FLOOR': 64, 'BAD_REF_PIXEL': 131072, 'CHARGELOSS': 128, 'DEAD': 1024, 'DO_NOT_USE': 1, 'DROPOUT': 8, 'FLUX_ESTIMATED': 268435456, 'GOOD': 0, 'HOT': 2048, 'JUMP_DET': 4, 'LOW_QE': 8192, 'MSA_FAILED_OPEN': 536870912, 'NONLINEAR': 65536, 'NON_SCIENCE': 512, 'NO_FLAT_FIELD': 262144, 'NO_GAIN_VALUE': 524288, 'NO_LIN_CORR': 1048576, 'NO_SAT_CHECK': 2097152, 'OPEN': 67108864, 'OTHER_BAD_PIXEL': 1073741824, 'OUTLIER': 16, 'PERSISTENCE': 32, 'RC': 16384, 'REFERENCE_PIXEL': 2147483648, 'SATURATED': 2, 'TELEGRAPH': 32768, 'UNRELIABLE_BIAS': 4194304, 'UNRELIABLE_DARK': 8388608, 'UNRELIABLE_ERROR': 256, 'UNRELIABLE_FLAT': 33554432, 'UNRELIABLE_SLOPE': 16777216, 'WARM': 4096}

Methods Documentation

add_model(model)

Add a single input model to the resampling.

Parameters:

modelImageModel

A JWST data model to be resampled.

create_output_jwst_model(ref_input_model=None)

Create a new blank model and update its meta with info from ref_input_model.

Parameters:

ref_input_modelJwstDataModel, optional

The reference input model from which to copy meta data.

Returns:

ImageModel

A new blank model with updated meta data.

finalize()

Perform final computations and set output model values and metadata.

input_model_to_dict(model, weight_type, enable_var, compute_err)

Convert a data model to a dictionary of keywords and values expected by stcal.resample.

Parameters:

modelDataModel

A JWST data model.

weight_typestr

The weighting type for adding models’ data.

enable_varbool

Indicates whether to resample variance arrays.

compute_errstr

The method to compute the output model’s error array.

Returns:

dict

A dictionary of keywords and values expected by stcal.resample.

resample_group(indices)

Resample multiple input images belonging to a single group_id.

If output_jwst_model was created by a previous call to this method, output_jwst_model as well as other arrays (weights, context, etc.) will be cleared. Upon completion, this method calls finalize() to compute final values for various attributes of the resampled model (e.g., exposure start and end times, etc.)

Parameters:

indiceslist

Indices of models in input_models model library (used to initialize this object) that have the same group_id and need to be resampled together.

Returns:

output_jwst_model

Resampled model with populated data, weights, error arrays and other attributes.

resample_many_to_many(in_memory=True)

Resample many inputs to many outputs where outputs have a common frame.

Coadd only different detectors of the same exposure, i.e. map NRCA5 and NRCB5 onto the same output image, as they image different areas of the sky.

Used for outlier detection.

Parameters:

in_memorybool, optional

Indicates whether to return a ModelLibrary with resampled models loaded in memory or whether to serialize resampled models to files on disk and return a ModelLibrary with only the associacion info. See https://stpipe.readthedocs.io/en/latest/model_library.html#on-disk-mode for more details.

Returns:

ModelLibrary

A library of resampled models.

resample_many_to_one()

Resample and coadd many inputs to a single output.

Used for stage 3 resampling.

Returns:

ImageModel

The resampled and coadded image.

reset_arrays(n_input_models=None)

Initialize/reset between finalize() and add_model() calls.

Resets or re-initializes Drizzle objects, ModelBlender, output model and arrays, and time counters. Output WCS and shape are not modified from Resample object initialization. This method needs to be called before calling add_model() for the first time after finalize() was previously called.

Parameters:

n_input_modelsint, None, optional

Number of input models expected to be resampled. When provided, this is used to estimate memory requirements and optimize memory allocation for the context array.

static update_fits_wcsinfo(model)

Update FITS WCS keywords of the resampled image.

Parameters:

modelImageModel

The resampled image

update_output_model(model, info_dict)

Add meta information to the output model.

Parameters:

modelImageModel

The output model to be updated.

info_dictdict

A dictionary containing information about the resampling process.