Detailed spaceKLIP API

spaceKLIP.analysistools module

class spaceKLIP.analysistools.AnalysisTools(database)[source]

Bases: object

The spaceKLIP astrophysical analysis tools class.

calibrate_contrast(subdir='calcon', rawcon_subdir='rawcon', rawcon_filetype='npy', companions=None, injection_seps='default', injection_pas='default', injection_flux_sigma=20, multi_injection_spacing=None, use_saved=False, thrput_fit_method='median', plot_xlim=(0, 10), plot_style=None, **kwargs)[source]

Compute a calibrated contrast curve relative to the host star flux.

Parameters

subdirstr, optional: Name of the directory where the data products shall be saved. The default is ‘calcon’.
rawcon_subdirstr, optional: Name of the directory where the raw contrast data products have been saved. The default is ‘rawcon’.
rawcon_filetypestr: Save filetype of the raw contrast files.
companionslist of list of three float, optional: List of companions to be masked before computing the raw contrast. For each companion, there should be a three element list containing [RA offset (arcsec), Dec offset (arcsec), mask radius (lambda/D)]. The default is None.
injection_seps1D-array, optional: List of separations to inject companions at (arcsec).
injection_pas1D-array, optional: List of position angles to inject companions at (degrees).
injection_flux_sigmafloat, optional: The peak flux of all injected companions in units of sigma, relative to the 1sigma contrast at the injected separation.
multi_injection_spacingint, None, optional: Spacing between companions injected in a single image. If companions are too close then it can pollute the recovered flux. Set to ‘None’ to inject only one companion at a time (lambda/D).
use_savedbool, optional: Toggle to use existing saved injected and recovered fluxes instead of repeating the process.
thrput_fit_methodstr, optional: Method to use when fitting/interpolating the measure KLIP throughputs across all of the injection positions. ‘median’ for a median of PAs at with the same separation. ‘log_grow’ for a logistic growth function.

Returns

None.

extract_companions(companions, starfile, mstar_err, spectral_type='G2V', planetfile=None, klmode='max', date='auto', use_fm_psf=True, flip_fmpsf_xy=None, highpass=False, fitmethod='mcmc', minmethod=None, fitkernel='diag', subtract=True, inject=False, remove_background=False, save_preklip=False, overwrite=True, subdir='companions', save_figures=True, use_epsf=False, fov_pix=65, save_psf=False, **kwargs)[source]

Extract the best fit parameters of a number of companions from each reduction in the spaceKLIP reductions database.

Parameters

companionslist of list of three float, optional: List of companions to be extracted. For each companion, there should be a three element list containing guesses for [RA offset (arcsec), Dec offset (arcsec), contrast].
starfilepath: Path of VizieR VOTable containing host star photometry or two column TXT file with wavelength (micron) and flux (Jy).
mstar_errfloat or dict of float: Error on the host star magnitude. If float, will use the same value for each filter. If dict of float, the dictionary keys must be the JWST filters in use and a different value can be used for each filter.
spectral_typestr, optional: Host star spectral type for the stellar model SED. The default is ‘G2V’.
planetfilepath: Path of VizieR VOTable containing companion photometry or two column TXT file with wavelength (micron) and flux (Jy).
klmodeint or ‘max’, optional: KL mode for which the companions shall be extracted. If ‘max’, then the maximum possible KL mode will be used. The default is ‘max’.
datestr, optional: Observation date in the format ‘YYYY-MM-DDTHH:MM:SS.MMM’. Will query for the wavefront measurement closest in time to the given date. If ‘auto’, will grab date from the FITS file header. If None, then the default WebbPSF OPD is used (RevAA). The default is ‘auto’.
use_fm_psfbool, optional: If True, use a FM PSF generated with pyKLIP, otherwise use a more simple integration time-averaged model offset PSF which does not incorporate any KLIP throughput losses. The default is True.
flip_fmpsf_xystr, optional: If ‘x’, flip the x-axis of the FM PSF. If ‘y’, flip the y-axis of the FM PSF. ‘xy’ or ‘yx’ for both.
highpassbool or float, optional: If float, will apply a high-pass filter to the FM PSF and KLIP dataset. The default is False.
fitmethod‘mcmc’ or ‘nested’, optional: Sampling algorithm which shall be used. If None and minmethod not None, it will mock the MCMC fit results using the initial guesses and perform only the Gaussian convolution fit to estimate extension. The default is ‘mcmc’.
minmethod: str, optional: scipy.optimize.minimize minimization method which shall be used to fit for the extension of the source. The default is None.
fitkernelstr, optional: Pyklip.fitpsf.FitPSF covariance kernel which shall be used for the Gaussian process regression. The default is ‘diag’.
subtractbool, optional: If True, subtract each extracted companion from the pyKLIP dataset before fitting the next one in the list. The default is True.
injectbool, optional: Instead of fitting for a companion at the guessed location and contrast, inject one into the data.
remove_backgroundbool, optional: Remove a constant background level from the KLIP-subtracted data before fitting the FM PSF. The default is False.
save_preklipbool, optional: Save the stage 2 files when injecting/killing a companion? The default is False.
overwritebool, optional: If True, compute a new FM PSF and overwrite any existing one, otherwise try to load an existing one and only compute a new one if none exists yet. The default is True.
subdirstr, optional: Name of the directory where the data products shall be saved. The default is ‘companions’.
save_figuresbool, optional: Save the plots in a PDF?
save_psf: bool, optional: Save the best fit PSF for each companion as a FITS file.

Returns

None.

raw_contrast(starfile, spectral_type='G2V', companions=None, overwrite_crpix=None, subdir='rawcon', output_filetype='npy', plot_xlim=(0, 10), plot_ylim=(None, 1), save_figures=True, plot_style=None, **kwargs)[source]

Compute the raw contrast relative to the provided host star flux.

Parameters

starfilepath: Path of VizieR VOTable containing host star photometry or two column TXT file with wavelength (micron) and flux (Jy).
spectral_typestr, optional: Host star spectral type for the stellar model SED. The default is ‘G2V’.
companionslist of list of three float, optional: List of companions to be masked before computing the raw contrast. For each companion, there should be a three element list containing [RA offset (arcsec), Dec offset (arcsec), mask radius (lambda/D)]. The default is None.
overwrite_crpixtuple of two float, optional: Overwrite the PSF center with the (CRPIX1, CRPIX2) values provided here (in 1-indexed coordinates). This is required for Coron3 data! The default is None.
subdirstr, optional: Name of the directory where the data products shall be saved. The default is ‘rawcon’.
output_filetypestr: File type to save the raw contrast information to. Options are ‘ecsv’ or ‘npy’.
save_figuresbool, optional: Save the plots in a PDF?

Returns

None.

spaceKLIP.analysistools.best_convfit_and_residuals(fma, minmethod='Powell', bounds=None, initial_params=None, fig=None)[source]

Fit the companion with a 2D Gaussian using a minimization algorithm and evaluate the sigma_x, sigma_y and theta. Then, generate a plot of the best fit FM compared with the data_stamp and also the residuals

Parameters

fma: fitpsf.FMAstrometry: FMAstronomy object with the desired properties
method: str: Minimization method. Default is ‘Powell’.
bounds: list of 2-D arrays.: list of 3 elements, containing the min, max values for the sigma_x, sigma_y and theta_degrees parameters for the 2-D gaussian kernel. Default is None.
initial_params: list of floats: list of initial guesses for the sigma_x, sigma_y and theta_degrees parameters for the 2-D gaussian kernel. Default is None.
fig: matplotlib.Figure: if not None, a matplotlib Figure object, function will make a new one. Default is None.

Returns

fig: matplotlib.Figure: the Figure object. If input fig is None, function will make a new one
result: array: Array containing the fitted parameters from the minimization process

spaceKLIP.analysistools.estimate_extended(target, offset_psf, bounds=None, initial_params=None, method='Powell')[source]

Fit for extended sources with a 2D gaussian kernel.

Parameters

target: 2-D array.: The target tile containing the companion to be fitted.
offset_psf: 2-D array.: The PSF of the companion to be used for the fit.
bounds: list of 2-D arrays.: list of 3 elements, containing the min, max values for the sigma_x, sigma_y and theta_degrees parameters for the 2-D gaussian kernel. If None, use default bounds = [(0.01, 20),(0.01, 20),(-180, 180)]
initial_params: list of floats: list of initial guesses for the sigma_x, sigma_y and theta_degrees parameters for the 2-D gaussian kernel. If None, use default initial_params = [0.1, 0.1, 0]
method: str: Minimization method. Default is ‘Powell’.

Returns

result: array: Array containing the fitted parameters from the minimization process

spaceKLIP.analysistools.inject_and_recover(raw_dataset, injection_psf, injection_seps, injection_pas, injection_spacing, injection_fluxes, klip_args, retrieve_fwhm, true_companions=None, **kwargs)[source]

Function to inject synthetic PSFs into a pyKLIP dataset, then perform KLIP subtraction, then calculate the flux losses from the KLIP process.

Parameters

raw_datasetpyKLIP dataset: A pyKLIP dataset which companions will be injected into and KLIP will be performed on.
injection_psf2D-array: The PSF of the companion to be injected.
injection_seps1D-array: List of separations to inject companions at (pixels).
injection_pas1D-array: List of position angles to inject companions at (degrees).
injection_spacingint, None: Spacing between companions injected in a single image. If companions are too close then it can pollute the recovered flux. Set to ‘None’ to inject only one companion at a time (pixels).
injection_fluxes1D-array: Same size as injection_seps, units should correspond to the image units. This is the peak flux of the injection.
klip_argsdict: Arguments to be passed into the KLIP subtraction process
retrieve_fwhmfloat: Full-Width Half-Maximum value to estimate the 2D gaussian fit when retrieving the companion fluxes.
true_companionslist of list of three float, optional: List of real companions to be masked before computing the raw contrast. For each companion, there should be a three element list containing [RA offset (pixels), Dec offset (pixels), mask radius (pixels)]. The default is None.

Returns

all_sepsnp.array: Array containing the separations of all injected companions across all images.
all_pasnp.array: Array containing the position angles of all injected companions across all images.
all_inj_fluxesnp.array: Array containing the injected peak fluxes of all injected companions across all images.
all_retr_fluxesnp.array: Array containing the retrieved peak fluxes of all injected companions across all images.

spaceKLIP.analysistools.loss_function(params, offset_psf, target_array)[source]: Loss function for the minimization process in fit_for_extended_sources.

spaceKLIP.classpsfsubpipeline module

spaceKLIP.classpsfsubpipeline.run_obs(database, kwargs={}, subdir='psfsub')[source]

Run classical PSF subtraction on the input observations database.

Parameters

databasespaceKLIP.Database

SpaceKLIP database on which classical PSF subtraction shall be run.

kwargsdict, optional

Keyword arguments for the classical PSF subtraction method. Available keywords are:

combine_dithersbool, optional
Combine all dither positions into a single reference PSF or subtract each dither position individually? The default is True.
save_rollsbool, optional
Save each processed roll separately? The default is False.
mask_brightfloat, optional
Mask all pixels brighter than this value before minimizing the PSF subtraction residuals.

The default is {}.

subdirstr, optional

Name of the directory where the data products shall be saved. The default is ‘psfsub’.

Returns

None.

spaceKLIP.coron1pipeline module

class spaceKLIP.coron1pipeline.Coron1Pipeline_spaceKLIP(**kwargs)[source]

Bases: Detector1Pipeline

The spaceKLIP JWST stage 1 pipeline class.

Apply all calibration steps to raw JWST ramps to produce a 2-D slope product. Custom sub-class of Detector1Pipeline with modifications for coronagraphic data.

Included steps are: group_scale, dq_init, saturation, ipc, superbias, refpix, rscd, firstframe, lastframe, linearity, dark_current, reset, persistence, jump detection, ramp_fit, and gain_scale.

apply_rateint_outliers(rateints_model, ramp_model, **kwargs)[source]

Get pixel outliers in rateint model and apply to ramp model DQ

Parameters

rateints_model~jwst.datamodels.CubeModel: Rateints model to use for outlier detection
ramp_model~jwst.datamodels.RampModel: Ramp model to update with outlier flags

Keyword Args

sigma_cutfloat: Sigma cut for outlier detection. Default is 10.
nint_minint: Minimum number of integrations required for outlier detection. Default is 10.

class_alias = 'calwebb_coron1'

do_pseudo_refpix(input, **kwargs)[source]

Do a pseudo reference pixel correction

Flag the requested edge rows and columns as reference pixels, run the JWST stage 1 refpix step, and then unflag those “pseudo” reference pixels.

Parameters

inputjwst.datamodel: Input JWST datamodel to be processed.
kwargskeyword arguments: Default JWST stage 1 refpix step keyword arguments.

Returns

resjwst.datamodel: Output JWST datamodel.

do_refpix(input, **kwargs)[source]

Do the default or a custom pseudo reference pixel correction.

If full frame, perform RefPix as normal. If no ref rows or columns specified, then perform RefPix as normal.

Otherwise, temporarily set reference rows and columns in the DQ flags and force the reference correction. Can set number of reference rows and column via the nlower, nupper, nleft, nright attributes.

Parameters

inputjwst.datamodel: Input JWST datamodel to be processed.
kwargskeyword arguments: Default JWST stage 1 refpix step keyword arguments.

Returns

resjwst.datamodel: Output JWST datamodel.

do_saturation(input, **kwargs)[source]

Do the default or a custom saturation correction.

Parameters

inputjwst.datamodel: Input JWST datamodel to be processed.
kwargskeyword arguments: Default JWST stage 1 saturation step keyword arguments.

Returns

resjwst.datamodel: Output JWST datamodel.

process(input)[source]

Process an input JWST datamodel with the spaceKLIP JWST stage 1 pipeline.

Parameters

inputjwst.datamodel: Input JWST datamodel to be processed.

Returns

outputjwst.datamodel: Output JWST datamodel.

run_step(step_obj, input, save_results=None, **kwargs)[source]

Run a JWST pipeline step.

Parameters

step_objjwst.step: JWST pipeline step to be run.
inputjwst.datamodel: Input JWST datamodel to be processed.
save_resultsbool, optional: Save the JWST pipeline step product? None will default to the JWST pipeline step default. The default is None.

Returns

resjwst.datamodel: Output JWST datamodel.

setup_output(input)[source]: Determine output file name suffix

spec = "\n save_intermediates = boolean(default=False) # Save all intermediate step results\n rate_int_outliers = boolean(default=False) # Flag outlier pixels in rateints\n return_rateints = boolean(default=False) # Return rateints or rate product?\n stage_1overf = string(default='ints') # Where in process to perform 1/f noise removal; groups or ints\n "

class spaceKLIP.coron1pipeline.MaskGroupsStep(name=None, parent=None, config_file=None, _validate_kwds=True, **kws)[source]

Bases: JwstStep

Mask particular groups prior to ramp fitting

class_alias = 'maskgroups'

process(input)[source]: Mask particular groups prior to ramp fitting

spec = '\n mask_sigma_med = float(default=3) #Only mask pixels Nsigma above the median\n mask_window = integer(default=2) #Also mask pixels within N pixels of a masked pixel\n '

spaceKLIP.coron1pipeline.apply_masking_prechecks(steps)[source]

spaceKLIP.coron1pipeline.prepare_group_masking_advanced(steps, observations, refpath, reftype, quiet=False)[source]: Advanced group masking method which computes the group mask on a pixel by pixel and reference cube by reference cube basis

spaceKLIP.coron1pipeline.prepare_group_masking_basic(steps, observations, quiet=False)[source]

spaceKLIP.coron1pipeline.prepare_group_masking_custom(steps, observations, quiet=False)[source]

spaceKLIP.coron1pipeline.run_obs(database, steps={}, subdir='stage1', overwrite=True, quiet=False, verbose=False, **kwargs)[source]

Run the JWST stage 1 detector pipeline on the input observations database. This customized implementation can:

Do a custom saturation correction where only the bottom/top/left/right and not the diagonal pixels next to a saturated pixel are flagged.
Do a pseudo reference pixel correction. Therefore, flag the requested edge rows and columns as reference pixels, run the JWST stage 1 refpix step, and unflag the pseudo reference pixels again. Only applicable for subarray data.
Remove 1/f noise spatial striping in NIRCam data.

Parameters

databasespaceKLIP.Database

SpaceKLIP database on which the JWST stage 1 pipeline shall be run.

stepsdict, optional

See here for how to use the steps parameter: https://jwst-pipeline.readthedocs.io/en/latest/jwst/user_documentation/running_pipeline_python.html#configuring-a-pipeline-step-in-python Custom step parameters are:

saturation/grow_diagonalbool, optional
Flag also diagonal pixels (or only bottom/top/left/right)? The default is True.
saturation/flag_rcsatbool, optional
Flag RC pixels as always saturated? The default is False.
refpix/nlowerint, optional
Number of rows at frame bottom that shall be used as additional reference pixels. The default is 4.
refpix/nupperint, optional
Number of rows at frame top that shall be used as additional reference pixels. The default is 4.
refpix/nrow_offint, optional
Number of rows to offset the reference pixel region from the bottom/top of the frame. The default is 0.
ramp_fit/save_calibrated_rampbool, optional
Save the calibrated ramp? The default is False.

Additional useful step parameters:

saturation/n_pix_grow_satint, optional
Number of pixels to grow for saturation flagging. Default is 1.
ramp_fit/suppress_one_groupbool, optional
If True, skips slope calc for pixels with only 1 available group. Default: False.
ramp_fit/maximum_coresstr, optional
max number of parallel processes to create during ramp fitting. ‘none’, ‘quarter’, ‘half’, or ‘all’. Default: ‘none’.

Default is {}. Each of these parameters can be passed directly through kwargs.

subdirstr, optional

Name of the directory where the data products shall be saved. The default is ‘stage1’.

overwritebool, optional

Overwrite existing files? Default is True.

quietbool, optional

Use progress bar to track progress instead of messages. Overrides verbose and sets it to False. Default is False.

verbosebool, optional

Print all info messages? Default is False.

Keyword Args

save_resultsbool, optional: Save the JWST pipeline step products? The default is True.
save_calibrate_rampbool: Save intermediate step that is the calibrated ramp? Default is False.
save_intermediatesbool, optional: Save intermediate steps, such as dq_init, saturation, refpix, jump, linearity, ramp, etc. Default is False.
return_rateintsbool, optional: Return the rateints model instead of rate? Default is False.
rate_int_outliersbool, optional: Flag outlier pixels in rateints? Default is False. Uses the cube_outlier_detection function and requires a minimum of 5 integrations.
flag_rcsatbool, optional: Flag known RC pixels as always saturated? Default is False.
stage_1overfstr, optional: Where in the pipeline process to perform 1/f noise removal? Either at the ‘groups’ or ‘ints’ level. Default is ‘ints’.
skip_ktcbool, optional: Remove kTC noise by fitting ramp data to get bias? Useful for looking at linearized ramp data. Default: False.
skip_fnoisebool, optional: Skip 1/f noise removal? Default: False.
skip_fnoise_vertbool, optional: Skip removal of vertical striping? Default: False. Not applied if 1/f noise correction is skipped.
skip_chargebool, optional: Skip charge migration flagging step? Default: False.
skip_jumpbool, optional: Skip jump detection step? Default: False.
skip_darkbool, optional: Skip dark current subtraction step? Default is True for subarrays and False for full frame data. Dark current cal files for subarrays are really low SNR.
skip_ipcbool, optional: Skip IPC correction step? Default: False.
skip_persistencebool, optional: Skip persistence correction step? Default: True. Doesn’t currently do anything.

Returns

None.

spaceKLIP.coron1pipeline.run_single_file(fitspath, output_dir, steps={}, verbose=False, **kwargs)[source]

Run the JWST stage 1 detector pipeline on a single file.

WARNING: Will overwrite exiting files.

This customized implementation can:

Do a custom saturation correction where only the bottom/top/left/right and not the diagonal pixels next to a saturated pixel are flagged.
Do a pseudo reference pixel correction. Therefore, flag the requested edge rows and columns as reference pixels, run the JWST stage 1 refpix step, and unflag the pseudo reference pixels again. Only applicable for subarray data.
Remove 1/f noise spatial striping in NIRCam data.

Parameters

fitspathstr

Path to the input FITS file (uncal.fits).

output_dirstr

Path to the output directory to save the resulting data products.

stepsdict, optional

See here for how to use the steps parameter: https://jwst-pipeline.readthedocs.io/en/latest/jwst/user_documentation/running_pipeline_python.html#configuring-a-pipeline-step-in-python Custom step parameters are:

saturation/grow_diagonalbool, optional
Flag also diagonal pixels (or only bottom/top/left/right)? The default is True.
saturation/flag_rcsatbool, optional
Flag RC pixels as always saturated? The default is False.
refpix/nlowerint, optional
Number of rows at frame bottom that shall be used as additional reference pixels. The default is 4.
refpix/nupperint, optional
Number of rows at frame top that shall be used as additional reference pixels. The default is 4.
refpix/nrow_offint, optional
Number of rows to offset the reference pixel region from the bottom/top of the frame. The default is 0.
ramp_fit/save_calibrated_rampbool, optional
Save the calibrated ramp? The default is False.

Additional useful step parameters:

saturation/n_pix_grow_satint, optional
Number of pixels to grow for saturation flagging. Default is 1.
ramp_fit/suppress_one_groupbool, optional
If True, skips slope calc for pixels with only 1 available group. Default: False.
ramp_fit/maximum_coresstr, optional
max number of parallel processes to create during ramp fitting. ‘none’, ‘quarter’, ‘half’, or ‘all’. Default: ‘none’.

The default is {}.

Keyword Args

save_resultsbool, optional: Save the JWST pipeline step products? The default is True.
save_calibrate_rampbool: Save intermediate step that is the calibrated ramp? Default is False.
save_intermediatesbool, optional: Save intermediate steps, such as dq_init, saturation, refpix, jump, linearity, ramp, etc. Default is False.
return_rateintsbool, optional: Return the rateints model instead of rate? Default is False.
rate_int_outliersbool, optional: Flag outlier pixels in rateints? Default is False. Uses the cube_outlier_detection function and requires a minimum of 5 integrations.
flag_rcsatbool, optional: Flag known RC pixels as always saturated? Default is False.
stage_1overfstr, optional: Where in the pipeline process to perform 1/f noise removal? Either at the ‘groups’ or ‘ints’ level. Default is ‘ints’.
skip_ktcbool, optional: Remove kTC noise by fitting ramp data to get bias? Useful for looking at linearized ramp data. Default: False.
skip_fnoisebool, optional: Skip 1/f noise removal? Default: False.
skip_fnoise_vertbool, optional: Skip removal of vertical striping? Default: False. Not applied if 1/f noise correction is skipped.
skip_chargebool, optional: Skip charge migration flagging step? Default: False.
skip_jumpbool, optional: Skip jump detection step? Default: False.
skip_darkbool, optional: Skip dark current subtraction step? Default is True for subarrays and False for full frame data. Dark current cal files for subarrays are really low SNR.
skip_ipcbool, optional: Skip IPC correction step? Default: False.
skip_persistencebool, optional: Skip persistence correction step? Default: True. Doesn’t currently do anything.

Returns

Pipeline output, either rate or rateint data model.

spaceKLIP.coron2pipeline module

class spaceKLIP.coron2pipeline.Coron2Pipeline_spaceKLIP(**kwargs)[source]

Bases: Image2Pipeline

The spaceKLIP JWST stage 2 pipeline class.

class_alias = 'calwebb_coron2'

process(input)[source]

Process an input JWST datamodel with the spaceKLIP JWST stage 2 pipeline.

Parameters

inputjwst.datamodel: Input JWST datamodel to be processed.

Returns

all_reslist of jwst.datamodel: List of output JWST datamodels.

spec = '\n save_intermediates = boolean(default=False) # Save all intermediate step results\n '

spaceKLIP.coron2pipeline.run_obs(database, steps={}, subdir='stage2', do_rates=False, overwrite=True, quiet=False, verbose=False, **kwargs)[source]

Run the JWST stage 2 image pipeline on the input observations database. This customized implementation will also run the ‘outlier_detection’ step if not skipped.

Parameters

databasespaceKLIP.Database

SpaceKLIP database on which the JWST stage 2 image pipeline shall be run.

stepsdict, optional

See here for how to use the steps parameter: https://jwst-pipeline.readthedocs.io/en/latest/jwst/user_documentation/running_pipeline_python.html#configuring-a-pipeline-step-in-python Custom step parameters are:

n/a

The default is {}.

subdirstr, optional

Name of the directory where the data products shall be saved. The default is ‘stage2’.

do_ratesbool, optional

In addition to processing rateints files, also process rate files if they exist? The default is False.

overwritebool, optional

Overwrite existing files? Default is False.

quietbool, optional

Use progress bar to track progress instead of messages. Overrides verbose and sets it to False. Default is False.

verbosebool, optional

Print all info messages? Default is False.

Keyword Args

save_resultsbool, optional: Save the JWST pipeline products? The default is True.
skip_bgbool, optional: Skip the background subtraction step? The default is False.
skip_photombool, optional: Skip the photometric correction step? The default is False.
skip_resamplebool, optional: Skip the resampling (drizzle) step? While the default is set to False, this step only applies to normal imaging modes and only on rate/cal files (not rateints/calints). For coronagraphic observations, resampling occurs in Stage 3.
skip_wcsbool, optional: Skip the WCS assignment step? The default is False.
skip_flatbool, optional: Skip the flat field correction step? The default is False.
skip_outlierbool, optional: Skip the outlier detection step? The default is False except for target acquisition subarray data, which will always be True.

Returns

None.

spaceKLIP.coron2pipeline.run_single_file(fitspath, output_dir, steps={}, verbose=False, **kwargs)[source]

Run the JWST stage 2 image pipeline on a single file.

This customized implementation will also run the ‘outlier_detection’ step if not skipped.

Parameters

databasespaceKLIP.Database: SpaceKLIP database on which the JWST stage 2 image pipeline shall be run.
stepsdict, optional: See here for how to use the steps parameter: https://jwst-pipeline.readthedocs.io/en/latest/jwst/user_documentation/running_pipeline_python.html#configuring-a-pipeline-step-in-python Custom step parameters are: - n/a The default is {}.
subdirstr, optional: Name of the directory where the data products shall be saved. The default is ‘stage2’.
do_ratesbool, optional: In addition to processing rateints files, also process rate files if they exist? The default is False.
overwritebool, optional: Overwrite existing files? Default is False.
quietbool, optional: Use progress bar to track progress instead of messages. Overrides verbose and sets it to False. Default is False.
verbosebool, optional: Print all info messages? Default is False.

Keyword Args

save_resultsbool, optional: Save the JWST pipeline products? The default is True.
skip_bgbool, optional: Skip the background subtraction step? The default is False.
skip_photombool, optional: Skip the photometric correction step? The default is False.
skip_resamplebool, optional: Skip the resampling (drizzle) step? While the default is set to False, this step only applies to normal imaging modes and only on rate/cal files (not rateints/calints). For coronagraphic observations, resampling occurs in Stage 3.
skip_wcsbool, optional: Skip the WCS assignment step? The default is False.
skip_flatbool, optional: Skip the flat field correction step? The default is False.
skip_outlierbool, optional: Skip the outlier detection step? The default is False except for target acquisition subarray data, which will always be True.

Returns

None.

spaceKLIP.coron3pipeline module

class spaceKLIP.coron3pipeline.Coron3Pipeline_spaceKLIP(*args, **kwargs)[source]

Bases: Coron3Pipeline

The spaceKLIP JWST stage 3 pipeline class.

spaceKLIP.coron3pipeline.make_asn_file(database, key, output_dir)[source]

Make the association file required by the JWST stage 3 coronagraphy pipeline for the provided concatenation.

Parameters

databasespaceKLIP.Database: SpaceKLIP database for which the association file shall be made.
keystr: Database key of the concatenation for which the association file shall be made.
output_dirpath: Path of the directory where the association file shall be saved.

Returns

asnpathpath: Path of the association file.

spaceKLIP.coron3pipeline.run_obs(database, steps={}, subdir='stage3')[source]

Run the JWST stage 3 coronagraphy pipeline on the input observations database.

Parameters

databasespaceKLIP.Database: SpaceKLIP database on which the JWST stage 3 coronagraphy pipeline shall be run.
stepsdict, optional: See here for how to use the steps parameter: https://jwst-pipeline.readthedocs.io/en/latest/jwst/user_documentation/running_pipeline_python.html#configuring-a-pipeline-step-in-python Custom step parameters are: - n/a The default is {}.
subdirstr, optional: Name of the directory where the data products shall be saved. The default is ‘stage3’.

Returns

None.

spaceKLIP.database module

class spaceKLIP.database.Database(output_dir)[source]

Bases: object

The central spaceKLIP database class.

adjust_dir(dir_path, data_type)[source]

Adjust the directory of the data products.

Parameters

dir_pathstr: New directory of the data products.
data_typestr: Type of data to adjust (‘red’ for reduced data, ‘obs’ for observations data, ‘src’ for source data).

Returns

None.

print_obs(include_fitsfiles=False)[source]

Print an abbreviated version of the observations database.

Parameters

include_fitsfilesbool, optional: Include the FITS file and PSF mask paths in the output. The default is False.

Returns

None.

print_red(include_fitsfiles=False)[source]

Print an abbreviated version of the reductions database.

Parameters

include_fitsfilesbool, optional: Include the FITS file and PSF mask paths in the output. The default is False.

Returns

None.

print_src(include_fitsfiles=False)[source]

Print an abbreviated version of the source database.

Parameters

include_fitsfilesbool, optional: Include the FITS file paths in the output. The default is False.

Returns

None.

read_jwst_s012_data(datapaths, psflibpaths=None, bgpaths=None, cr_from_siaf=False, assoc_using_targname=True)[source]

Read JWST stage 0 (uncal), 1 (rate or rateints), or 2 (cal or calints) data into the Database.obs dictionary. It contains a table of metadata for each concatenation, which are identified automatically based on instrument, filter, pupil mask, and image mask. The tables can be edited by the user at any stage of the data reduction process and spaceKLIP will continue with the updated metadata (e.g., modified host star position).

Parameters

datapathslist of paths: List of paths of the input JWST data. SpaceKLIP will try to automatically identify science data, PSF references, target acquisition frames, and MIRI background observations. If spaceKLIP does not get things right, you may use the ‘psflibpaths’ and ‘bgpaths’ keywords below.
psflibpathslist of paths, optional: List of paths of the input PSF references. Make sure that they are NOT duplicated in the ‘datapaths’. The default is None.
bgpathslist of paths, optional: List of paths of the input MIRI background observations. Make sure that they ARE duplicated in the ‘datapaths’ or ‘psflibpaths’. The default is None.
assoc_using_targnamebool, optional: If True associate TA and BG observations to their corresponding SCI and REF observations based on the target name from the APT file. Otherwise, only consider the instrument parameters to distinguish between SCI and REF TA/BG. The default is True.

Returns

None.

read_jwst_s3_data(datapaths, cr_from_siaf=False)[source]

Read JWST stage 3 data (this can be i2d data from the official JWST pipeline, or data products from the pyKLIP and classical PSF subtraction pipelines implemented in spaceKLIP) into the Database.red dictionary. It contains a table of metadata for each concatenation, which are identified automatically based on instrument, filter, pupil mask, and image mask. The tables can be edited by the user at any stage of the data reduction process and spaceKLIP will continue with the updated metadata (e.g., modified host star position).

Parameters

datapathslist of paths: List of paths of the input JWST data.

Returns

None.

read_jwst_s4_data(datapaths)[source]

Read JWST stage 4 data (spaceKLIP PSF fitting products) into the Database.src dictionary. It contains a list of tables of metadata for each concatenation, which are identified automatically based on instrument, filter, pupil mask, and image mask.

Parameters

datapathslist of paths: List of paths of the input JWST data.

Returns

None.

summarize()[source]: Succinctly summarize the contents of the observations database, i.e., how many files are present at each level of reduction, what kind (SCI, REF, TA), etc.

Returns

None.

update_obs(key, index, fitsfile, maskfile=None, nanmaskfile=None, nints=None, effinttm=None, xoffset=None, yoffset=None, crpix1=None, crpix2=None, maskcenx=None, maskceny=None, nanmaskcenx=None, nanmaskceny=None, starcenx=None, starceny=None, crop_shiftx=None, crop_shifty=None, align_shift=None, center_shift=None, align_mask=None, center_mask=None, blurfwhm=None, update_pxar=False)[source]

Update the content of the observations database.

Parameters

keystr: Database key of the observation to be updated.
indexint: Database index of the observation to be updated.
fitsfilepath: New FITS file path for the observation to be updated.
maskfilepath, optional: New PSF mask path for the observation to be updated. The default is None.
nanmaskfilepath, optional: New NaNs mask path for the observation to be updated. The default is None.
nintsint, optional: New number of integrations for the observation to be updated. The default is None.
effinttmfloat, optional: New effective integration time (s) for the observation to be updated. The default is None.
xoffsetfloat, optional: New PSF x-offset (mas) for the observation to be updated. The default is None.
yoffsetfloat, optional: New PSF y-offset (mas) for the observation to be updated. The default is None.
crpix1float, optional: New WCS reference x-position (pix, 1-indexed) for the observation to be updated. The default is None.
crpix2float, optional: New WCS reference y-position (pix, 1-indexed) for the observation to be updated. The default is None.
maskcenxfloat, optional: New mask x-position (pix, 1-indexed) for the observation to be updated. The default is None.
maskcenyfloat, optional: New mask y-position (pix, 1-indexed) for the observation to be updated. The default is None.
nanmaskcenxfloat, optional: New nanmask x-position (pix, 1-indexed) for the observation to be updated. The default is None.
nanmaskcenyfloat, optional: New nanmask y-position (pix, 1-indexed) for the observation to be updated. The default is None.
starcenxfloat, optional: New star x-position (pix, 1-indexed) for the observation to be updated. The default is None.
starcenyfloat, optional: New star y-position (pix, 1-indexed) for the observation to be updated. The default is None.
crop_shiftxtuple, optional: Stores shifts in x due to any cropping. The default is None.
crop_shiftytuple, optional: Stores shifts in y due to any cropping. The default is None.
align_shift: object: Array of shift values to recenter science frames. The default is None.
center_shift: object: Array of shift values to align science frames. The default is None.
align_mask: object: Array of shift values to align masks. The default is None.
center_mask: object: Array of shift values to recenter masks. The default is None.
blurfwhmfloat, optional: New FWHM for the Gaussian filter blurring (pix) for the observation to be updated. The default is None.
update_pxarbool, optional: Update the pixel area column of the database based on the FITS file header information? The default is False.

Returns

None.

update_src(key, index, tab)[source]

Update the content of the source database.

Parameters

keystr: Database key of the source to be updated.
indexint: Database index of the source to be updated.
tabastropy.table.Table: Astropy table of the companions to be saved to the source database.

Returns

None.

spaceKLIP.database.create_database(output_dir, pid=None, obsids=None, input_dir=None, psflibpaths=None, bgpaths=None, assoc_using_targname=True, verbose=True, readlevel='012', cr_from_siaf=False, **kwargs)[source]

Create a spaceKLIP database from JWST data

Automatically searches for uncal.fits in the input directory and creates a database of the JWST data. Only works for stage0, stage1, or stage2 data by default; set readlevel=3 to read in stage 3 outputs.

Parameters

output_dirstr: Directory to save the database.
pidstr: Program ID.
obsidslist of ints, optional: List of observation numbers. If not set, will search for all observations in the input directory.
input_dirstr: Directory containing the JWST data. If not set, will search for MAST directory.
psflibpathslist of paths, optional: List of paths of the input PSF references. Make sure that they are NOT duplicated in the ‘datapaths’. The default is None.
bgpathslist of paths, optional: List of paths of the input MIRI background observations. Make sure that they ARE duplicated in the ‘datapaths’ or ‘psflibpaths’. The default is None.
assoc_using_targnamebool, optional: Associate observations using the TARGNAME keyword. The default is True.
readlevelstr or int: Level of data products to read in, either ‘012’ (or an integer 0,1,2) to read in individual exposures, or ‘3’ to read in level-3 PSF-subtracted products, or ‘4’ to read in extracted PSF fitting products.
verbosebool, optional: Print information to the screen. The default is True.

Keyword Arguments

scastr: Name of detector (e.g., ‘along’ or ‘a3’)
filtstr: Return files observed in given filter.
file_typestr: ‘uncal.fits’, ‘rateints.fits’, ‘calints.fits’, etc.
exp_typestr: Exposure type such as NRC_TACQ, NRC_TACONFIRM
vst_grp_actstr: The _<gg><s><aa>_ portion of the file name. hdr0[‘VISITGRP’] + hdr0[‘SEQ_ID’] + hdr0[‘ACT_ID’]
apernamestr: Name of aperture (e.g., NRCA5_FULL)
apername_ppsstr: Name of aperture from PPS (e.g., NRCA5_FULL)
readlevelstr or int: Set this to 3 invoke the code for re-reading in level 3 output products. By default, only levels 0,1,2 data will be read and indexed.

spaceKLIP.expjumpramp module

class spaceKLIP.expjumpramp.Covar(read_times, pedestal=False)[source]

Bases: object

class Covar holding read and photon noise components of alpha and beta and the time intervals between the resultant midpoints

calc_bias(countrates, sig, cvec, da=1e-07)[source]

Calculate the bias in the best-fit count rate from estimating the covariance matrix. This calculation is derived in the paper.

Parameters

countrates [array of count rates at which the bias is desired]
sig [float, single read noise]
cvec [weight vector on resultant differences for initial estimation of count rate for the covariance matrix]

Optional argument: 4. da [float, fraction of the count rate plus sig**2 to use for finite difference estimate of the derivative.]

Returns

bias [array, bias of the best-fit count rate from using cvec
plus the observed resultants to estimate the covariance matrix]

class spaceKLIP.expjumpramp.ExperimentalJumpRampStep(name=None, parent=None, config_file=None, _validate_kwds=True, **kws)[source]

Bases: JwstStep

Experimental step based on Tim Brandt’s jump detection and ramp fitting algorithm.

class_alias = 'experimental_jumpramp'

create_alldiffs2use(datamodel, shape)[source]

Parameters

datamodelJWST datamodel: JWST ramp datamodel
shapelist: Shape of the corresponding diffs array

Returns

all_diffs2usendarray: Array flagging which diffs should be used in the jump detection and ramp fitting

create_covar(datamodel)[source]

Create the covariance matrix

Parameters

datamodelJWST datamodel: JWST ramp datamodel

Returns

CCovar() object: Covariance matrix object

create_diffs(datamodel, C)[source]

Create the differenced frames

Parameters

datamodelJWST datamodel: JWST ramp datamodel
CCovar() object: Covariance matrix object

Returns

diffsndarray: Scaled differenced frames of a given set of ramp images.

create_dq_ints(datamodel)[source]

Turn the 2D and 4D pixel DQ to 3D DQ

Parameters

datamodelJWST datamodel: JWST ramp datamodel

Returns

dqintsndarray: 3D data quality array, corresponding to each integration

get_subarray_ref(datamodel, filename, trim=True)[source]

Get a reference file and extract on subarray

Parameters

datamodelJWST datamodel: JWST ramp datamodel
filenamestr: File name string for the given reference file, e.g. ‘gain’ or ‘readnoise’
trimbool: Boolean for trimming reference file to the subarray of the provided datamodel.

Returns

subrefndarray: Loaded reference file array.

process(input)[source]

Perform jump detection and ramp fitting

Parameters

inputJWST pipeline input: Appropriate input to JWST pipeline step, e.g. fits file name or preloaded JWST datamodel.

Returns

img_modelJWST datamodel: JWST datamodel equivalent to a “rate.fits” file.
int_modelJWST datamodel: JWST datamodel equivalent to a “rateints.fits” file.

produce_ramp_images(datamodel, noise_scale)[source]

Function to assemble relevant data and run jump detection and ramp fitting.

Parameters

datamodelJWST datamodel: JWST ramp datamodel
noise_scalefloat: Scale factor to apply to the readnoise

Returns

resultsdict: Dictionary containing equivalents of the integration level ‘SCI’, ‘ERR’, ‘VAR_POISSON’, and ‘VAR_RDNOISE’ arrays.

set_dnu_to_nan(ramp_results, dq_ints)[source]

Set any do not use pixels to NaNs

Parameters

resultsdict: Dictionary containing equivalents of the integration level ‘SCI’, ‘ERR’, ‘VAR_POISSON’, and ‘VAR_RDNOISE’ arrays.
dq_intsndarray: 3D data quality array

Returns

resultsdict: Dictionary containing equivalents of the integration level ‘SCI’, ‘ERR’, ‘VAR_POISSON’, and ‘VAR_RDNOISE’ arrays.

spec = '\n use = boolean(default=False) # Use regular pipeline by default\n nproc = integer(default=4) # Number of processes to use\n noise_scale = float(default=1) #Scale factor for noise estimate\n nan_dnu = boolean(default=True) #Set do not use pixels to NaN?\n '

update_groupdq(datamodel, flagged_diffs)[source]

Update group DQ based on detected jumps

Parameters

datamodelJWST datamodel: JWST ramp datamodel
flagged_diffsndarray: Flagged array of size the same as differenced frames, with jumps marked.

Returns

updated_datamodelJWST datamodel: JWST ramp datamodel with updated groupdq

weighted_average(sci, var_poisson, var_rdnoise, err)[source]

Compute a weighted average of a 3D multi-integration dataset

Parameters

scindarray: Array of science data
var_poissonndarray: Array of poission variance
var_rdnoisendarray: Array of readnoise variance
errndarray: Array of uncertainties

Returns

w_av_scindarray: Weighted average array of science data
w_av_vpondarray: Weighted average array of poisson variance
w_av_vrdndarray: Weighted average array of readnoise variance
w_av_errndarray: Weighted average array of uncertainties

class spaceKLIP.expjumpramp.Ramp_Result[source]

Bases: object

fill_masked_reads(diffs2use)[source]

Replace countrates, uncertainties, and chi squared values that are NaN because resultant differences were doubly omitted. For these cases, revert to the corresponding values in with fewer omitted resultant differences to get the correct values without double-coundint omissions.

Parameters

diffs2use [a 2D array matching self.countrate_oneomit in
shape with zero for resultant differences that were masked and one for differences that were not masked]

This function replaces the relevant entries of self.countrate_twoomit, self.chisq_twoomit, self.uncert_twoomit, self.countrate_oneomit, and self.chisq_oneomit in place. It does not return a value.

spaceKLIP.expjumpramp.fit_ramps(diffs, Cov, sig, countrateguess=None, diffs2use=None, detect_jumps=False, resetval=0, resetsig=inf, rescale=True, dn_scale=10)[source]

Function fit_ramps. Fits ramps to read differences using the covariance matrix for the read differences as given by the diagonal elements and the off-diagonal elements.

Parameters

diffs [resultant differences, shape (ndiffs, npix)]
Cov [class Covar, holds the covariance matrix information]
sig [read noise, 1D array, shape (npix)]

Optional Arguments: 4. countrateguess [array of shape (npix): count rates to be used

to estimate the covariance matrix. Default None, in which case the average difference will be used, replacing negative means with zeros.]

diffs2use [shape (ndiffs, npix), boolean mask of whether to use
each resultant difference for each pixel. Default None]
detect_jumps [run the jump detection machinery leaving out
single and consecutive resultant differences. Default False]
resetval [float or array of shape (npix): priors on the reset
values. Default 0. Irrelevant unless Cov.pedestal is True.]
resetsig [float or array of shape (npix): uncertainties on the
reset values. Default np.inf, i.e., reset values have flat priors. Irrelevant unless Cov.pedestal is True.]
rescale [boolean, scale the covariance matrix internally to avoid
possible overflow/underflow problems for long ramps. Slightly increases computational cost. Default True. ]

Returns: Class Ramp_Result holding lots of information

spaceKLIP.expjumpramp.getramps(countrate, sig, readtimes, nramps=10)[source]

Function getramps: make some synthetic ramps

Parameters

countrate [electrons/time]
sig [single read read noise, electrons]
readtimes [list of values or lists for the times of reads. If
a list of lists, times for reads that are averaged together to produce a resultant.]

Optional Arguments: 4. nramps [number of ramps desired, default 10]

Returns

counts [electrons in each read, shape (nreads, nramps)]

spaceKLIP.expjumpramp.jumpramp_column(i, int_diffs, C, sig, int_diffs2use)[source]

Function to run of jump/ramp on specific column of pixels, assumes an input 4D array of data at the group level.

Parameters

iint: Index of the integration to run ramp fitting over.
int_diffsndarray: Array of differenced frames
CCovar() object: Covariance matrix object
signdarray: Uncertainty on the data
int_diffs2usendarray: The integration level differenced frames to be used during ramp fitting.

Returns

resultRamp_Result() object: Output object from ramp fitting algorithm
int_diffs2usendarray: Updated integration level differenced frames to be used during ramp fitting.

spaceKLIP.expjumpramp.jumpramp_column_helper(args)[source]

Function to unpack parameters in multiprocessing

Parameters

argslist: List of arguments to be passed to the jumpramp calculation

Returns

result.countratendarray: Array of countrates from ramp fitting.
result.uncertndarray: Array of uncertainties from ramp fitting.
result.var_poissonndarray: Array of poisson variance from ramp fitting.
result.var_rdnoisendarray: Array of readnoise from ramp fitting.
int_diffs2usendarray: The integration level differenced frames to be used during ramp fitting.

spaceKLIP.expjumpramp.mask_jumps(diffs, Cov, sig, threshold_oneomit=20.25, threshold_twoomit=23.8, diffs2use=None)[source]

Function mask_jumps implements a likelihood-based, iterative jump detection algorithm.

Parameters

diffs [resultant differences]
Cov [class Covar, holds the covariance matrix information. Must
be based on differences alone (i.e. without the pedestal)]
sig [read noise, 1D array]

Optional arguments: 4. threshold_oneomit [float, minimum chisq improvement to exclude

a single resultant difference. Default 20.25, i.e., 4.5 sigma]

threshold_twoomit [float, minimum chisq improvement to exclude
two sequential resultant differences. Default 23.8, i.e., 4.5 sigma]
diffs2use [a 2D array of the same shape as d, one for resultant
differences that appear ok and zero for resultant differences flagged as contaminated. These flagged differences will be ignored throughout jump detection, which will only flag additional differences and overwrite the data in this array. Default None]

Returns

diffs2use [a 2D array of the same shape as d, one for resultant
differences that appear ok and zero for resultant differences flagged as contaminated.]
countrates [a 1D array of the count rates after masking the pixels
and resultants in diffs2use.]

spaceKLIP.fnoise_clean module

class spaceKLIP.fnoise_clean.CleanFullFrame(data, mask, exclude_outliers=True, bg_sub=False, flatten_model=False, slowaxis=2, nout=4, channel_averaging=False, **kwargs)[source]

Bases: object

Clean 1/f noise from full frame images

Use CleanSubarray instances to clean each channel separately. First removes common channel noise, then cleans the residuals of each channel. Final full frame model is stored in model attribute. Intended for use on Level 1 or 2 pipeline products on any type of image product (group data, rateint, calint, rate, cal, etc). Suggest removing average signal levels from data and running this on the residuals, which better reveal the 1/f noise structure.

Inspired by NSClean by Bernie Rauscher (https://arxiv.org/abs/2306.03250), however instead of using FFTs and Matrix multiplication, this class uses Savitzky-Golay filtering to model the 1/f noise and subtract it from the data. This is significantly faster than the FFT approach and provides similar results.

By default, function assumes such that the slowscan runs vertically along the y-axis (slowaxis=2), while the fast scan direction runs horizontally. Direction (left to right or right to left) is irrelevant. If the slowscan runs horizontally along x-axis in your data, then set slowaxis=1 during intialization.

average_channels()[source]: Create an average channel image representing the common 1/f noise

clean(model_type='savgol', vertical_corr=False, **kwargs)[source]

Clean the data

Overwrites data in-place with the cleaned data.

Parameters

model_typestr: Must be ‘median’, ‘mean’, or ‘savgol’. For ‘mean’ case, it uses a robust mean that ignores outliers and NaNs. The ‘median’ case uses np.nanmedian. The ‘savgol’ case uses a Savitzky-Golay filter to model the 1/f noise, iteratively rejecting outliers from the model fit relative to the median model. The default is ‘savgol’.
vertical_corrbool: Apply a horizontal correction to the data. This is useful for removing horizontal striping. The default is False.

Keyword Args

niterint: Number of iterations to use for rejecting outliers during the model fit. If the number of rejected pixels does not change between iterations, then the fit is considered converged and the loop is broken.
winsizeint: Size of the window filter. Should be an odd number.
orderint: Order of the polynomial used to fit the samples.
per_linebool: Smooth each channel line separately with the hopes of avoiding edge discontinuities.
maskbool image or None: An image mask of pixels to ignore. Should be same size as im_arr. This can be used to mask pixels that the filter should ignore, such as stellar sources or pixel outliers. A value of True indicates that pixel should be ignored.
modestr: Must be ‘mirror’, ‘constant’, ‘nearest’, ‘wrap’ or ‘interp’. This determines the type of extension to use for the padded signal to which the filter is applied. When mode is ‘constant’, the padding value is given by cval. When the ‘interp’ mode is selected (the default), no extension is used. Instead, a degree polyorder polynomial is fit to the last window_length values of the edges, and this polynomial is used to evaluate the last window_length // 2 output values.
cvalfloat: Value to fill past the edges of the input if mode is ‘constant’. Default is 0.0.

fit(model_type='savgol', vertical_corr=False, **kwargs)[source]

property flatten_model: Use Coronagraphic ND acquisition square?

class spaceKLIP.fnoise_clean.CleanSubarray(data, mask, exclude_outliers=True, bg_sub=False, flatten_model=False, slowaxis=2, **kwargs)[source]

Bases: object

1/f noise modeling and subtraction for HAWAII-2RG subarrays.

CleanSubarray is the base class for removing residual correlated read noise from generic JWST near-IR Subarray images. It is intended for use on Level 1 or 2 pipeline products on any type of image product (group data, rateint, calint, rate, cal, etc). Suggest removing average signal levels from data and running this on the residuals, which better reveal the 1/f noise structure.

Inspired by NSClean by Bernie Rauscher (https://arxiv.org/abs/2306.03250), however instead of using FFTs and Matrix multiplication, this class uses Savitzky-Golay filtering to model the 1/f noise and subtract it from the data. This is significantly faster than the FFT approach and provides similar results.

This function assumes such that the slowscan runs vertically along the y-axis, while the fast scan direction runs horizontally. Direction (left to right or right to left) is irrelevant. If the slowscan runs horizontally along x-axis in your data, then make sure to transpose before passing to this class.

bg_subtract(box_size=32, filter_size=5, sigma=3, maxiters=5)[source]: Use photutils Background2D to remove spatially varying background

clean(model_type='savgol', vertical_corr=False, **kwargs)[source]

Clean the data

Overwrites data in-place with the cleaned data.

Parameters

model_typestr: Must be ‘median’, ‘mean’, or ‘savgol’. For ‘mean’ case, it uses a robust mean that ignores outliers and NaNs. The ‘median’ case uses np.nanmedian. The ‘savgol’ case uses a Savitzky-Golay filter to model the 1/f noise, iteratively rejecting outliers from the model fit relative to the median model. The default is ‘savgol’.
vertical_corrbool: Apply a horizontal correction to the data. This is useful for removing horizontal striping. The default is False.

Keyword Args

niterint: Number of iterations to use for rejecting outliers during the model fit. If the number of rejected pixels does not change between iterations, then the fit is considered converged and the loop is broken.
winsizeint: Size of the window filter. Should be an odd number.
orderint: Order of the polynomial used to fit the samples.
per_linebool: Smooth each channel line separately with the hopes of avoiding edge discontinuities.
maskbool image or None: An image mask of pixels to ignore. Should be same size as im_arr. This can be used to mask pixels that the filter should ignore, such as stellar sources or pixel outliers. A value of True indicates that pixel should be ignored.
modestr: Must be ‘mirror’, ‘constant’, ‘nearest’, ‘wrap’ or ‘interp’. This determines the type of extension to use for the padded signal to which the filter is applied. When mode is ‘constant’, the padding value is given by cval. When the ‘interp’ mode is selected (the default), no extension is used. Instead, a degree polyorder polynomial is fit to the last window_length values of the edges, and this polynomial is used to evaluate the last window_length // 2 output values.
cvalfloat: Value to fill past the edges of the input if mode is ‘constant’. Default is 0.0.

fit(model_type='savgol', vertical_corr=False, **kwargs)[source]

Return the model which is just median of each row

Parameters

model_typestr: Must be ‘median’, ‘mean’, or ‘savgol’. For ‘mean’ case, it uses a robust mean that ignores outliers and NaNs. The ‘median’ case uses np.nanmedian. The ‘savgol’ case uses a Savitzky-Golay filter to model the 1/f noise, iteratively rejecting outliers from the model fit relative to the median model. The default is ‘savgol’.
vertical_corrbool: Apply a vertical correction to the data. This is useful for removing vertical striping. The default is False.

Keyword Args

niterint: Number of iterations to use for rejecting outliers during the model fit. If the number of rejected pixels does not change between iterations, then the fit is considered converged and the loop is broken. For ‘savgol’ only.

property nx: Number of columns in the image

property ny: Number of rows in the image

class spaceKLIP.fnoise_clean.OneOverfStep(*args, **kwargs)[source]

Bases: JwstStep

OneOverfStep: Apply 1/f noise correction

Works on RampModel, CubeModel, and ImageModel data products.

For RampModel, it creates a master slope image, then subtracts a group-dependent flux image to produce a residual image. Then for each group residual image, we model the 1/f noise using a Savitzky-Golay filter.

For CubeModel, we create an average of all slope images, then subtract from each slope image to create a series of residual images. We then apply a Savitzky-Golay filter to each residual image to model the 1/f noise.

Full frame channels are handled by first removing with common channel noise (taking into account flips in the readout direction), then channel-dependent 1/f noise is modeled and applied to a complete model of the full frame image.

If only a single integration is present, then a mask is applied to exclude pixels with large flux values. These pixels are excluded during the model fitting process.

class_alias = '1overf'

proc_CubeModel(input)[source]

Apply 1/f noise correction to a JWST CubeModel

Parameters

inputJWST data model: Input science data model to be corrected. Should be a CubeModel such as rateints or calints.

proc_ImageModel(input)[source]: Apply 1/f noise correction to a JWST ImageModel

proc_RampModel(input)[source]

Apply 1/f noise correction to a JWST RampModel

Parameters

inputJWST data model: Input science data model to be corrected. Should be a linearized RampModel.

process(input)[source]

Apply 1/f noise correction to a JWST RampModel

Parameters

inputJWST data model: Input science data model to be corrected. Should be linearized.

Returns

outputJWST data model: Output science data model with 1/f noise correction applied.

quick_plot(image, mask, model, im_diff=None)[source]

spec = "\n model_type = option('median', 'mean', 'savgol', default='savgol') # Type of model to fit\n sat_frac = float(default=0.5) # Maximum saturation fraction for fitting\n combine_ints = boolean(default=True) # Combine integrations before ramp fitting\n vertical_corr = boolean(default=True) # Apply vertical correction\n nproc = integer(default=4) # Number of processes to use\n "

spaceKLIP.fnoise_clean.channel_smooth_savgol(im_arr, winsize=127, order=3, per_line=False, mask=None, **kwargs)[source]

Channel smoothing using savgol filter

Function for generating a map of the 1/f noise within a series of input images.

Copied over from pynrc (https://github.com/JarronL/pynrc) by Jarron Leisenring.

Parameters

im_arrndarray: Input array of images (intended to be a cube of output channels). Shape should either be (ny, chsize) to smooth a single channel or (nchan, ny, chsize) for multiple channels. Each image is operated on separately. If only two dimensions, then only a single input image is assumed. NaN’s will be interpolated over.

Keyword Args

winsizeint: Size of the window filter. Should be an odd number.
orderint: Order of the polynomial used to fit the samples.
per_linebool: Smooth each channel line separately with the hopes of avoiding edge discontinuities.
maskbool image or None: An image mask of pixels to ignore. Should be same size as im_arr. This can be used to mask pixels that the filter should ignore, such as stellar sources or pixel outliers. A value of True indicates that pixel should be ignored.
modestr: Must be ‘mirror’, ‘constant’, ‘nearest’, ‘wrap’ or ‘interp’. This determines the type of extension to use for the padded signal to which the filter is applied. When mode is ‘constant’, the padding value is given by cval. When the ‘interp’ mode is selected (the default), no extension is used. Instead, a degree polyorder polynomial is fit to the last window_length values of the edges, and this polynomial is used to evaluate the last window_length // 2 output values.
cvalfloat: Value to fill past the edges of the input if mode is ‘constant’. Default is 0.0.

spaceKLIP.fnoise_clean.create_bkg_mask(data, bpmask=None, nsigma=3, niter=3)[source]

Returns a mask of background pixels

Selects background pixels based on a median value and a sigma threshold. First, select pixels that are below the median value of the data. Select pixels that deviate from the median by more than nsigma.

spaceKLIP.fnoise_clean.fit_slopes_to_ramp_data(input, sat_frac=0.5, combine_ints=False)[source]

Fit slopes to each integration

Uses custom cube_fit function to fit slopes to each integration. Returns array of slopes and bias values for each integration. Bias and slope arrays have shape (nints, ny, nx).

Parameters

inputjwst.datamodel: Input JWST datamodel housing the data to be fit.
sat_fracfloat: Saturation threshold for fitting. Values above this fraction of the saturation level are ignored. Default is 0.5 to ensure that the fit is within the linear range.
combine_intsbool: Average all integrations into a single array before fitting. Return an (bias_arr, slope_mean). Default is False.

spaceKLIP.fnoise_clean.get_bkg(data, bpmask=None, nsigma=3, complex=False)[source]

Background subtraction of an image using photutils

Similar to algorithm by Chris Willott at https://github.com/chriswillott/jwst/blob/master/image1overf.py

class spaceKLIP.fnoise_clean.kTCSubtractStep(name=None, parent=None, config_file=None, _validate_kwds=True, **kws)[source]

Bases: JwstStep

kTCSubtractStep: Subtract kTC noise from ramp data.

class_alias = 'removektc'

process(input)[source]: Subtract kTC noise from data.

spec = '\n sat_frac = float(default=0.5) # Maximum saturation fraction for fitting\n '

spaceKLIP.fnoise_clean.make_clean_class(image, mask_good, noutputs, slowaxis, **kwargs)[source]

Create a Clean class instance

Parameters

imagendarray: Input image to be cleaned.
mask_goodndarray: Mask of good pixels. Pixels = True are modeled as background. Pixels = False are excluded from the background model.
noutputsint: Number of output amplifier channels.
slowaxisint: The slow scan axis. Must be 1 or 2. Default is 2. A setting of 1 implies output channels span the x-axis. A setting of 2 implies output channels span the y-axis.

spaceKLIP.fnoise_clean.mask_helper()[source]

Helper to handle indices and logical indices of a mask

Output: index, a function, with signature indices = index(logical_indices), to convert logical indices of a mask to ‘equivalent’ indices

Example:

>>> # linear interpolation of NaNs
>>> mask = np.isnan(y)
>>> x = mask_helper(y)
>>> y[mask]= np.interp(x(mask), x(~mask), y[~mask])

spaceKLIP.fnoise_clean.nfclean_mulitprocess_helper(args)[source]

Helper function for multiprocessing

The args parameter should be a tuple consisting of: (im_diff, im_mask, noutputs, slowaxis, flatten_model, model_type, vertical_corr)

spaceKLIP.imagetools module

class spaceKLIP.imagetools.ImageTools(database)[source]

Bases: object

The spaceKLIP image manipulation tools class.

align_frames(method='fourier', align_algo='leastsq', mask_override=None, msk_shp=8, shft_exp=1, align_to_file=None, scale_prior=False, kwargs={}, subdir='aligned', save_figures=True, plot_style=None)[source]

Align all SCI and REF frames to the first SCI frame.

Parameters

method‘fourier’ or ‘spline’ (not recommended), optional: Method for shifting the frames. The default is ‘fourier’.
align_algo‘leastsq’ or ‘header’: Algorithm to determine the alignment offsets. Default is ‘leastsq’, ‘header’ assumes perfect header offsets.
mask_overridestr, optional: Mask some pixels when cross correlating for shifts
msk_shpint, optional: Shape (height or radius, or [inner radius, outer radius]) for custom mask invoked by “mask_override”
shft_expfloat, optional: Take image to the given power before cross correlating for shifts, default is 1. For instance, 1/2 helps align nircam bar/narrow data (or other data with weird speckles)
align_to_filestr, optional: Path to FITS file to which all images shall be aligned. Needs to be a file with the same observational setup as all concatenations in the spaceKLIP database. Hence, this can only be applied to one observational setup at a time. The default is None.
scale_priorbool, optional: If True, tries to find a better prior for the scale factor instead of simply using 1. The default is False.
kwargsdict, optional: Keyword arguments for the scipy.ndimage.shift routine. The default is {}.
subdirstr, optional: Name of the directory where the data products shall be saved. The default is ‘aligned’.
save_figuresbool, optional: Save the plots in a PDF?

Returns

None.

blur_frames(fact='auto', types=['SCI', 'SCI_BG', 'REF', 'REF_BG'], subdir='blurred')[source]

Blur frames with a Gaussian filter.

Parameters

fact‘auto’ or ‘fix23’ or float or dict of list of float or None, optional: FWHM (pix) of the Gaussian filter. If ‘auto’, will compute the FWHM automatically based on the Nyquist sampling criterion for discrete data, which is FWHM = lambda / 2.3D, where D = 5.2 m for NIRCam coronagraphy and D = 6.5 m otherwise. If ‘fix23’, will always blur the data with a Gaussian kernel of FWHM = 2.3 pix, so that even bad pixels cause no more Fourier ripples. If dict of list of float, then the dictionary keys must match the keys of the observations database, and the number of entries in the lists must match the number of observations in the corresponding concatenation. Then, a different FWHM can be used for each observation. If None, the corresponding observation will be skipped. The default is ‘auto’.
typeslist of str, optional: List of data types for which the frames shall be blurred. The default is [‘SCI’, ‘SCI_BG’, ‘REF’, ‘REF_BG’].
subdirstr, optional: Name of the directory where the data products shall be saved. The default is ‘blurred’.

Returns

None.

calculate_alignment(method='fourier', align_algo='leastsq', mask_override=None, msk_shp=8, shft_exp=1, align_to_file=None, scale_prior=False, kwargs={}, subdir='aligned', save_figures=True, plot_style=None)[source]

Calculate shifts necessary to align all SCI and REF frames to the first SCI frame.

Parameters

method‘fourier’ or ‘spline’ (not recommended), optional: Method for shifting the frames. The default is ‘fourier’.
align_algo‘leastsq’ or ‘header’: Algorithm to determine the alignment offsets. Default is ‘leastsq’, ‘header’ assumes perfect header offsets.
mask_overridestr, optional: Mask some pixels when cross correlating for shifts
msk_shpint, optional: Shape (height or radius, or [inner radius, outer radius]) for custom mask invoked by “mask_override”
shft_expfloat, optional: Take image to the given power before cross correlating for shifts, default is 1. For instance, 1/2 helps align nircam bar/narrow data (or other data with weird speckles)
align_to_filestr, optional: Path to FITS file to which all images shall be aligned. Needs to be a file with the same observational setup as all concatenations in the spaceKLIP database. Hence, this can only be applied to one observational setup at a time. The default is None.
scale_priorbool, optional: If True, tries to find a better prior for the scale factor instead of simply using 1. The default is False.
kwargsdict, optional: Keyword arguments for the scipy.ndimage.shift routine. The default is {}.
subdirstr, optional: Name of the directory where the data products shall be saved. The default is ‘aligned’.
save_figuresbool, optional: Save the plots in a PDF?

Returns

None.

calculate_centers(method='fourier', use_ta=False, subpix_first_sci_only=False, first_sci_only=True, spectral_type='G2V', shft_exp=1, kwargs={}, highpass=False, subdir='recentered')[source]

Calculate shifts necessary to recenter frames so that the host star position is data.shape // 2. For NIRCam coronagraphy, use either a WebbPSF model or target acquisition data (if available) to determine the star’s position behind the coronagraphic mask in the first SCI frame. For MIRI coronagraphy, use target acquisition data (if available) to determine the star’s position behind the coronagraphic mask in the first SCI frame; otherwise, no shift is applied. Then, shift all other SCI and REF frames by the same amount. For all other data types, simply recenter the host star PSF.

Parameters

method‘fourier’ or ‘spline’ (not recommended), optional: Method for shifting the frames. The default is ‘fourier’.
use_ta: bool, optional: Use target acquisition data to determine the star’s position behind the coronagraphic mask in the first SCI frame? The default is False.
subpix_first_sci_onlybool, optional: By default, all frames will be recentered to subpixel precision. If ‘subpix_first_sci_only’ is True, then only the first SCI frame will be recentered to subpixel precision and all other SCI and REF frames will only be recentered to integer pixel precision by rolling the image. Can be helpful when working with poorly sampled data to avoid another interpolation step if the ‘align_frames’ routine is run subsequently. Only applicable to non-coronagraphic data. The default is False.
first_sci_onlybool, optional: Recenter all files and not just the first SCI file in each concate- nation. Only applicable to NIRCam/MIRI coronagraphy. The default is True.
spectral_typestr, optional: Host star spectral type for the WebbPSF model used to determine the star position behind the coronagraphic mask. The default is ‘G2V’.
shft_expfloat, optional: Take image to the given power before cross correlating for shifts, default is 1. For instance, 1/2 helps align NIRCam bar/narrow data (or other data with weird speckles).
kwargsdict, optional: Keyword arguments for the scipy.ndimage.shift routine. The default is {}.
subdirstr, optional: Name of the directory where the data products shall be saved. The default is ‘recentered’.

Returns

None.

calculate_centers_binary(kwargs={}, subdir='recentered')[source]

Recenter frames so that the host star position is data.shape // 2.

Parameters

kwargsdict, optional: Keyword arguments for the mcmc_tools.MCMCTools class. The default is {}.
subdirstr, optional: Name of the directory where the data products shall be saved. The default is ‘recentered’.

Returns

None.

clean_background(sigma=3.0, gaussian_smoothing={'sigma': 1.0, 'skip': True}, types=['SCI_BG', 'REF_BG'], subdir='bgcleaned')[source]

Clean data from any contaminating sources in background observations using sigma clipping. Used for MIRI background observations.

Parameters

sigmafloat, optional: Sigma clipping threshold for background cleaning. The default is 3.
gaussian_smoothingdict, optional: Dictionary with keyword arguments to use scipy.ndimage.gaussian_filter. This will smooth the backgrounds before the cleaning process. If ‘skip’ is True, no Gaussian smoothing will be applied. The default is {‘skip’:True, ‘sigma’:1.}.
typeslist of str, optional: List of data types for which background cleaning shall be applied. The default is [‘SCI_BG’, ‘REF_BG’].
subdirstr, optional: Name of the directory where the data products shall be saved. The default is ‘bgcleaned’.

Returns

None.

clean_bad_pixels(method='timemed+localmed+medfilt', timemed_kwargs=None, localmed_kwargs=None, medfilt_kwargs=None, interp2d_kwargs=None, astrofix_kwargs=None, types=['SCI', 'SCI_TA', 'SCI_BG', 'REF', 'REF_TA', 'REF_BG'], subdir='bpcleaned', restrict_to=None, plot=False)[source]

Clean bad pixels.

Parameters

methodstr, optional

Sequence of bad pixel cleaning methods to be run on the data. Different methods must be joined by a ‘+’ sign without whitespace. Available methods are:

timemed: replace pixels which are only bad in some frames with
their median value from the good frames.
localmed: replace bad pixels with the median value of their
surrounding good pixels.
medfilt: replace bad pixels with an image plane median filter.
interp2d: replace bad pixels with an interpolation of neighbouring pixels.
astrofix: is an astronomical image correction algorithm based on Gaussian Process Regression.

The default is ‘timemed+localmed+medfilt’.

timemed_kwargsdict, optional

Keyword arguments for the ‘timemed’ method. Available keywords are:

n/a

The default is {}.

localmed_kwargs: dict, optional

Keyword arguments for the ‘localmed’ method. Available keywords are:

shift_xlist of int, optional
Pixels in x-direction from which the median shall be computed. The default is [-1, 0, 1].
shift_ylist of int, optional
Pixels in y-direction from which the median shall be computed. The default is [-1, 0, 1].

The default is {}.

medfilt_kwargsdict, optional

Keyword arguments for the ‘medfilt’ method. Available keywords are:

sizeint, optional
Kernel size of the median filter to be used. The default is 4.

The default is {}.

interp2d_kwargs: dict, optional

Keyword arguments for the ‘interp2d’ method. Available keywords are:

sizeint, optional
Kernel size of the median filter to be used. The default is 4.

The default is {}.

astrofix_kwargs: dict, optional

Keyword arguments for the ‘astrofix’ method. Available keywords are:

The default is {}.

typeslist of str, optional

List of data types for which bad pixels shall be identified and fixed. The default is [‘SCI’, ‘SCI_TA’, ‘SCI_BG’, ‘REF’, ‘REF_TA’, ‘REF_BG’].

subdirstr, optional

methodstr, optional

Sequence of bad pixel cleaning methods to be run on the data. Different methods must be joined by a ‘+’ sign without whitespace. Available methods are:

dqarr: Uses DQ array to identify bad pixels.
timeints: To identify bad pixels in time.
sigclip: Uses sigma clipping to identify additional bad pixels.
custom: Uses a custom bad pixel map.

The default is ‘dqarr’.

set_dq_zerobool, optional

Toggle to start a new empty DQ array, or built upon the existing array. The default is True.

dqarr_kwargsdict, optional

Keyword arguments for the ‘dqarr’ identification method. Available keywords are:

flag_neighborsbool, optional
If True, the 4-connected neighbors (up, down, left, right) of each DO_NOT_USE pixel are evaluated and flagged if they are elevated relative to the local background, which is estimated from the surrounding diagonal pixels.
sigmaint, optional
Flag neighboring pixels with values greater than diag_med + sigma * diag_std.

The default is {}.

sigclip_kwargsdict, optional

Keyword arguments for the ‘sigclip’ identification methods. Available keywords are:

sigmafloat, optional
Sigma clipping threshold. The default is 5.
neg_sigmafloat, optional
Sigma clipping threshold for negative outliers. The default is 1.
shift_xlist of int, optional
Pixels in x-direction to which each pixel shall be compared to. The default is [-1, 0, 1].
shift_ylist of int, optional
Pixels in y-direction to which each pixel shall be compared to. The default is [-1, 0, 1].
diagonal_onlybool, optional
Only compare to diagonal neighbors? The default is False.
threshold_metricstr, optional
Whether to use standard deviation or MAD.
max_cluster_sizeint, optional
Maximum size of bad pixel clusters to be flagged. If None, no limit is applied.
cluster_dilate_radiusint, optional
Radius for dilating bad pixels before checking clustering. The default is 6 pixels.
modestr, optional

Sigma-clipping strategy used to identify bad pixels. Available options are:

‘local’Flags pixels that deviate from the median of their neighboring pixels.
Large negative outliers are also identified by comparing to background estimate.

‘local_weighted’ : Same as ‘local’, but includes the pixel uncertainty when computing the clipping threshold.
mask_psfbool, optional
Restrict bad pixel flagging inside the PSF?
crpix1/crpix2: float/float, optional
The center of the PSF.

The default is {}.

custom_kwargsdict, optional

Keyword arguments for the ‘custom’ method. The dictionary keys must match the keys of the observations database and the dictionary content must be binary bad pixel maps (1 = bad, 0 = good) with the same shape as the corresponding data. The default is {}.

The default is {}.

timeints_kwargsdict, optional

sigmafloat, optional
Sigma clipping threshold. The default is 5.
modestr, optional

Mode for detecting bad pixels. The default is ‘per_pixel’.
‘per_pixel’ : Computes the variation across integrations independently for each pixel. ‘group_pixels’ : Groups pixels by similar flux, computes the variation across integrations for each pixel, and compares each pixel’s variation to that of its corresponding flux group.
n_groupsint, optional
The number of groups if mode == ‘group_pixels’. The default is 25.
diagnostic_plotsbool, optional
Plot diagnostics?

The default is {}.

typeslist of str, optional

List of data types for which bad pixels shall be identified. The default is [‘SCI’, ‘SCI_TA’, ‘SCI_BG’, ‘REF’, ‘REF_TA’, ‘REF_BG’].

subdirstr, optional

Name of the directory where the data products shall be saved. The default is ‘bpfound’.

min_nancluster: int, optional

minimum number of pixels required to flag cluster of NaNs pixels. If None, the provided NaN mask in the database will be used. The default is None.

Returns

None.

find_bad_pixels_custom(data, erro, pxdq, key, custom_kwargs=None)[source]

Use a custom bad pixel map to flag additional bad pixels in the data.

Parameters

data3D-array: Input images.
erro3D-array: Input image uncertainties.
pxdq3D-array: Input binary bad pixel maps (1 = bad, 0 = good). Will be updated by the routine to include the newly flagged bad pixels.
keystr: Database key of the observation to be updated.
custom_kwargsdict, optional: Keyword arguments for the ‘custom’ method. The basic usage is dictionary with keys that must match the keys of the observations database and the dictionary content must be binary bad pixel maps (1 = bad, 0 = good) with the same shape as the corresponding data. It also allow for a more fine treatment to flag bad pixels at specific coordinates. In this case the dictionary content must be a list of [y,x] or [key,y,x] coordinates. The default is {}.

Returns

None.

find_bad_pixels_gradient(data, erro, pxdq, key, gradient_kwargs=None)[source]

find_bad_pixels_sigclip(data, erro, pxdq, NON_SCIENCE, sigclip_kwargs=None)[source]

Use an iterative sigma clipping algorithm to identify additional bad pixels in the data.

Parameters

data3D-array

Input images.

erro3D-array

Input image uncertainties.

pxdq3D-array

Input binary bad pixel maps (1 = bad, 0 = good). Will be updated by the routine to include the newly identified bad pixels.

NON_SCIENCE3D-array

Input binary non-science pixel maps (1 = bad, 0 = good). Will not be modified by the routine.

sigclip_kwargsdict, optional

Keyword arguments for the ‘sigclip’ method. Available keywords are:

sigmafloat, optional
Sigma clipping threshold. The default is 5.
neg_sigmafloat, optional
Sigma clipping threshold for negative outliers. The default is 1.
shift_xlist of int, optional
Pixels in x-direction to which each pixel shall be compared to. The default is [-1, 0, 1].
shift_ylist of int, optional
Pixels in y-direction to which each pixel shall be compared to. The default is [-1, 0, 1].
diagonal_onlybool, optional
Only compare to diagonal neighbors? The default is False.

-threshold_metricstr, optional: Whether to use standard deviation or MAD

max_cluster_sizeint, optional
Maximum size of bad pixel clusters to be flagged. If None, no limit is applied.
cluster_dilate_radiusint, optional
Radius for dilating bad pixels before checking clustering. The default is 6 pixels.
modestr, optional

Sigma-clipping strategy used to identify bad pixels. Available options are:

‘local’Flags pixels that deviate from the median of their neighboring pixels.
Large negative outliers are also identified by comparing to background estimate.

‘local_weighted’ : Same as ‘local’, but includes the pixel uncertainty when computing the clipping threshold.
mask_psfbool, optional
Restrict bad pixel flagging inside the PSF?
crpix1/crpix2: float/float, optional
The center of the PSF.

The default is {}.

Returns

None.

find_bad_pixels_timeints(data, erro, pxdq, NON_SCIENCE, timeints_kwargs=None)[source]

Identify bad pixels from temporal variations across integrations.

Parameters

data3D-array

Input images.

erro3D-array

Input image uncertainties.

pxdq3D-array

Input binary bad pixel maps (1 = bad, 0 = good). Will be updated by the routine to include the newly identified bad pixels.

NON_SCIENCE3D-array

Input binary non-science pixel maps (1 = bad, 0 = good). Will not be modified by the routine.

timeints_kwargsdict, optional

Keyword arguments for the ‘timeints’ method. Available keywords are:

sigmafloat, optional
Sigma clipping threshold. The default is 5.
modestr, optional

Mode for detecting bad pixels. The default is ‘per_pixel’.
‘per_pixel’ : Computes the variation across integrations independently for each pixel. ‘group_pixels’ : Groups pixels by similar flux, computes the variation across integrations for each pixel, and compares each pixel’s variation to that of its corresponding flux group.
n_groupsint, optional
The number of groups if mode == ‘group_pixels’. The default is 25.
diagnostic_plotsbool, optional
Plot diagnostics?

The default is {}.

Returns

None.

find_nircam_centers(data0, key, j, spectral_type='G2V', shft_exp=1, date=None, output_dir=None, fov_pix=65, oversample=2, use_coeff=False, highpass=False, save_figures=True, plot_style=None)[source]

Find the star position behind the coronagraphic mask using a WebbPSF model.

Parameters

data0list: List of frame for which the star position shall be determined.
keystr: Database key of the observation containing the first frame in data0.
jint: Database index of the observation containing the first frame in data0.
spectral_typestr, optional: Host star spectral type for the WebbPSF model used to determine the star position behind the coronagraphic mask. The default is ‘G2V’.
shft_expfloat, optional: Take image to the given power before cross correlating for shifts, default is 1.
datestr, optional: Observation date in the format ‘YYYY-MM-DDTHH:MM:SS.MMM’. The default is None.
output_dirpath, optional: Path of the directory where the data products shall be saved. The default is None.
oversampleint, optional: Factor by which the WebbPSF model shall be oversampled. The default is 2.
use_coeffbool, optional: Use pre-computed coefficients to generate the WebbPSF model. The default is False.
save_figuresbool, optional: Save the plots in a PDF?

Returns

xcfloat: Star x-position (pix, 0-indexed).
ycfloat: Star y-position (pix, 0-indexed).
xshiftfloat: X-shift between star and coronagraphic mask position (pix).
yshiftfloat: Y-shift between star and coronagraphic mask position (pix).

fix_bad_pixels(method='timemed+localmed+medfilt', sigclip_kwargs={}, custom_kwargs={}, timemed_kwargs={}, localmed_kwargs={}, medfilt_kwargs={}, types=['SCI', 'SCI_TA', 'SCI_BG', 'REF', 'REF_TA', 'REF_BG'], subdir='bpcleaned', restrict_to=None)[source]

TO BE DEPRECATED BY FIND_BAD_PIXELS() AND CLEAN_BAD_PIXELS() Identify and fix bad pixels.

Parameters

methodstr, optional

Sequence of bad pixel identification and cleaning methods to be run on the data. Different methods must be joined by a ‘+’ sign without whitespace. Available methods are:

sigclip: use sigma clipping to identify additional bad pixels.
custom: use a custom bad pixel map.
timemed: replace pixels which are only bad in some frames with
their median value from the good frames.
localmed: replace bad pixels with the median value of their
surrounding good pixels.
medfilt: replace bad pixels with an image plane median filter.

The default is ‘timemed+localmed+medfilt’.

sigclip_kwargsdict, optional

Keyword arguments for the ‘sigclip’ method. Available keywords are:

sigclipfloat, optional
Sigma clipping threshold. The default is 5.
shift_xlist of int, optional
Pixels in x-direction to which each pixel shall be compared to. The default is [-1, 0, 1].
shift_ylist of int, optional
Pixels in y-direction to which each pixel shall be compared to. The default is [-1, 0, 1].

The default is {}.

custom_kwargsdict, optional

Keyword arguments for the ‘custom’ method. The dictionary keys must match the keys of the observations database and the dictionary content must be binary bad pixel maps (1 = bad, 0 = good) with the same shape as the corresponding data. The default is {}.

timemed_kwargsdict, optional

Keyword arguments for the ‘timemed’ method. Available keywords are:

n/a

The default is {}.

localmed_kwargsdict, optional

Keyword arguments for the ‘localmed’ method. Available keywords are:

shift_xlist of int, optional
Pixels in x-direction from which the median shall be computed. The default is [-1, 0, 1].
shift_ylist of int, optional
Pixels in y-direction from which the median shall be computed. The default is [-1, 0, 1].

The default is {}.

medfilt_kwargsdict, optional

Keyword arguments for the ‘medfilt’ method. Available keywords are:

sizeint, optional
Kernel size of the median filter to be used. The default is 4.

The default is {}.

typeslist of str, optional

List of data types for which bad pixels shall be identified and fixed. The default is [‘SCI’, ‘SCI_TA’, ‘SCI_BG’, ‘REF’, ‘REF_TA’, ‘REF_BG’].

subdirstr, optional

Name of the directory where the data products shall be saved. The default is ‘bpcleaned’.

Returns

None.

fix_bad_pixels_astrofix(data, erro, pxdq, astrofix_kwargs=None, plot=False)[source]

Replace bad pixels with an algorithm based on Gaussian Process Regression. It trains itself to apply the optimal interpolation kernel for each image, performing multiple times better than median replacement and interpolation with a fixed kernel.

Parameters

data3D-array

Input images.

erro3D-array

Input image uncertainties.

pxdq3D-array

Input binary bad pixel maps (1 = bad, 0 = good). Will be updated by the routine to exclude the fixed bad pixels.

astrofix_kwargsdict, optional

Keyword arguments for the ‘astrofix’ method. Available keywords are:

sig_clip : float, optional

Pixels that are smaller than median + sig_clip * median absolute deviation of the image will not be used in the training process. Default: 10.

max_clip : float, optional

Pixels that are greater than max(image)/max_clip will not be used in the training process. Default: 5.

sig_data : float, optional

Measurement noise, assumed to be uniform. The kernel depends only on the ratio a/sig_data. Default: 1.

width : int, optional

Size of the window (width × width) used for interpolation. Default: 9.

init_guess : array-like, optional

Initial guess for the training process. By default, the 0th element gives the initial guess of a and the 1st element gives the initial guess of h. If the size of init_guess is 3, the training optimizes h_x and h_y separately instead of using h for all directions. In that case, the 1st element gives the initial guess of h_x, and the 2nd element gives the initial guess of h_y. Default: [1,1].

The default is {}.

plotbool, optional

Plot diagnostics?

Returns

None.

fix_bad_pixels_interp2d(data, erro, pxdq, interp2d_kwargs=None)[source]

Replace bad pixels with an interpolation of neighbouring pixels.

Parameters

data3D-array

Input images.

erro3D-array

Input image uncertainties.

pxdq3D-array

Input binary bad pixel maps (1 = bad, 0 = good). Will be updated by the routine to exclude the fixed bad pixels.

interp2d_kwargsdict, optional

Keyword arguments for the ‘interp2d’ method. Available keywords are:

sizeint, optional
Kernel size of the median filter to be used. The default is 5.
methodstr, optional
Interpolation method to be used. The default is ‘linear’. Available options are ‘nearest’, ‘linear’, and ‘cubic’.

The default is {}.

Returns

None.

fix_bad_pixels_localmed(data, erro, pxdq, localmed_kwargs=None)[source]

Replace bad pixels with the median value of their surrounding good pixels.

Parameters

data3D-array

Input images.

erro3D-array

Input image uncertainties.

pxdq3D-array

Input binary bad pixel maps (1 = bad, 0 = good). Will be updated by the routine to exclude the fixed bad pixels.

localmed_kwargsdict, optional

Keyword arguments for the ‘localmed’ method. Available keywords are:

shift_xlist of int, optional
Pixels in x-direction from which the median shall be computed. The default is [-1, 0, 1].
shift_ylist of int, optional
Pixels in y-direction from which the median shall be computed. The default is [-1, 0, 1].

The default is {}.

Returns

None.

fix_bad_pixels_medfilt(data, erro, pxdq, medfilt_kwargs=None)[source]

Replace bad pixels with an image plane median filter.

Parameters

data3D-array

Input images.

erro3D-array

Input image uncertainties.

pxdq3D-array

Input binary bad pixel maps (1 = bad, 0 = good). Will be updated by the routine to exclude the fixed bad pixels.

medfilt_kwargsdict, optional

Keyword arguments for the ‘medfilt’ method. Available keywords are:

sizeint, optional
Kernel size of the median filter to be used. The default is 4.

npixint or list of four int, optional: Number of pixels to be padded around the frames. If int, the same number of pixels will be padded on each side. If list of four int, a different number of pixels can be padded on the [left, right, bottom, top] of the frames. The default is 1.
npixint or list of four int, optional: target shape in pixels to reshape the frame into it. If int, the same shape will be applied to the each axis. If list of 2 int, a different shape owill be applied [x, y] to the frames. If none skip and use the default npix. The default is None.
cvalfloat, optional: Fill value for the padded pixels. The default is nan.
typeslist of str, optional: List of data types from which the frames shall be padded. The default is [‘SCI’, ‘SCI_BG’, ‘REF’, ‘REF_BG’].
subdirstr, optional: Name of the directory where the data products shall be saved. The default is ‘padded’.

Returns

None.

persistence_trimming(radius_pxl=4, ints_to_trim=2, types=['SCI', 'REF'], subdir='persistence_trimmed')[source]

Remove persistence artifacts from the initial N integrations by trimming a circular region around the persistence location. This is useful for MIRI 4QPM data where persistence artifacts from target acquisition can remain in early integrations.

Note that for this function to work, TA images must be included in the database and previous data reduction steps must have been performed to determine the persistence location.

Parameters

radius_pxlint, optional: Radius (in pixels) of the circular region around the persistence location to trim/mask. The default is 4.
ints_to_trimint, optional: Number of initial integrations to apply the persistence trimming to. The default is 2.
typeslist of str, optional: List of data types for which persistence trimming shall be applied. The default is [‘SCI’, ‘REF’].
subdirstr, optional: Name of the directory where the data products shall be saved. The default is ‘persistence_trimmed’.

Returns

None.

recenter_frames(method='fourier', subpix_first_sci_only=False, first_sci_only=True, spectral_type='G2V', shft_exp=1, kwargs={}, highpass=False, subdir='recentered')[source]

Recenter frames so that the host star position is data.shape // 2. For NIRCam coronagraphy, use a WebbPSF model to determine the star position behind the coronagraphic mask for the first SCI frame. Then, shift all other SCI and REF frames by the same amount. For MIRI coronagraphy, do nothing. For all other data types, simply recenter the host star PSF.

Parameters

method‘fourier’ or ‘spline’ (not recommended), optional: Method for shifting the frames. The default is ‘fourier’.
subpix_first_sci_onlybool, optional: By default, all frames will be recentered to subpixel precision. If ‘subpix_first_sci_only’ is True, then only the first SCI frame will be recentered to subpixel precision and all other SCI and REF frames will only be recentered to integer pixel precision by rolling the image. Can be helpful when working with poorly sampled data to avoid another interpolation step if the ‘align_frames’ routine is run subsequently. Only applicable to non-coronagraphic data. The default is False.
first_sci_onlybool, optional: Recenter all files and not just the first SCI file in each concate- nation. Only applicable to NIRCam coronagraphy. The default is True.
spectral_typestr, optional: Host star spectral type for the WebbPSF model used to determine the star position behind the coronagraphic mask. The default is ‘G2V’.
shft_expfloat, optional: Take image to the given power before cross correlating for shifts, default is 1. For instance, 1/2 helps align nircam bar/narrow data (or other data with weird speckles).
kwargsdict, optional: Keyword arguments for the scipy.ndimage.shift routine. The default is {}.
subdirstr, optional: Name of the directory where the data products shall be saved. The default is ‘recentered’.

Returns

None.

remove_frames(index=[0], types=['SCI', 'SCI_BG', 'REF', 'REF_BG'], subdir='removed')[source]

Remove individual frames from the data.

Parameters

indexint or list of int or dict of list of list of int, optional: Indices (0-indexed) of the frames to be removed. If int, then only a single frame will be removed from each observation. If list of int, then multiple frames can be removed from each observation. If dict of list of list of int, then the dictionary keys must match the keys of the observations database, and the number of entries in the lists must match the number of observations in the corresponding concatenation. Then, a different list of int can be used for each individual observation to remove different frames. The default is [0].
typeslist of str, optional: List of data types from which the frames shall be removed. The default is [‘SCI’, ‘SCI_BG’, ‘REF’, ‘REF_BG’].
subdirstr, optional: Name of the directory where the data products shall be saved. The default is ‘removed’.

Returns

None.

replace_nans(cval=0.0, types=['SCI', 'SCI_BG', 'REF', 'REF_BG'], subdir='nanreplaced')[source]

Replace all nans in the data with a constant value.

Parameters

cvalfloat, optional: Fill value for the nan pixels. The default is 0.
typeslist of str, optional: List of data types for which nans shall be replaced. The default is [‘SCI’, ‘SCI_BG’, ‘REF’, ‘REF_BG’].
subdirstr, optional: Name of the directory where the data products shall be saved. The default is ‘nanreplaced’.

Returns

None.

resample_frames(subdir='resampled')[source]

Resample frames applying distortion correction to the data

Parameters

subdirstr, optional
Name of the directory where the data products shall be saved. The default is ‘recentered’.

Returns

None.

shift_frames(method='fourier', kwargs={}, subdir='shifted')[source]

Calculate shifts necessary to align all SCI and REF frames to the first SCI frame.

Parameters

method‘fourier’ or ‘spline’ (not recommended), optional: Method for shifting the frames. The default is ‘fourier’.
kwargsdict, optional: Keyword arguments for the scipy.ndimage.shift routine. The default is {}.
subdirstr, optional: Name of the directory where the data products shall be saved. The default is ‘shifted’.

Returns

None.

subtract_background(nints_per_med=None, subdir='bgsub')[source]

Median subtract the corresponding background observations from the SCI and REF data in the spaceKLIP database.

Parameters

nints_per_medint: Number of integrations per median. For example, if you have a target + background dataset with 20 integrations each and nints_per_med is set to 5, a median of every 5 background images will be subtracted from the corresponding 5 target images. The default is None (i.e. a median across all images).
subdirstr, optional: Name of the directory where the data products shall be saved. The default is ‘bgsub’.

Returns

None.

subtract_background_godoy(types=['SCI', 'REF'], subdir='bgsub')[source]

Subtract the corresponding background observations from the SCI and REF data in the spaceKLIP database using a method developed by Nico Godoy.

Parameters

typeslist of str: File types to run the subtraction over.
subdirstr, optional: Name of the directory where the data products shall be saved. The default is ‘bgsub’.

Returns

None.

subtract_median(types=['SCI', 'SCI_TA', 'SCI_BG', 'REF', 'REF_TA', 'REF_BG'], method='border', sigma=3.0, borderwidth=32, subdir='medsub')[source]

Subtract the median from each frame. Clip everything brighter than 5- sigma from the background before computing the median.

Parameters

typeslist of str, optional: List of data types for which the median shall be subtracted. The default is [‘SCI’, ‘SCI_TA’, ‘SCI_BG’, ‘REF’, ‘REF_TA’, ‘REF_BG’].
subdirstr, optional: Name of the directory where the data products shall be saved. The default is ‘medsub’.

method : str, optional

‘robust’ for a robust median after masking out bright stars,

‘sigma_clipped’ for another version of robust median using astropy
sigma_clipped_stats on the whole image,

‘border’ for robust median on the outer border region only, to ignore the bright stellar PSF in the center,

‘simple’ for a simple np.nanmedian.

sigmafloat, optional: number of standard deviations to use for the clipping limit in sigma_clipped_stats, if the robust option is selected.
borderwidthint, optional: number of pixels to use when defining the outer border region, if the border option is selected. Default is to use the outermost 32 pixels around all sides of the image.

Returns

None.

subtract_nircam_coron_background(subdir='bgsub', mask_snr_threshold=2, r_excl_nfwhm=40, q_clip=5.0, align_wrapped=True, include_global_offset=True, include_stellar_psf_component=True, generate_plot=True, save_model=False, use_jbt_background=False, bgmodel_dir=None, background_sb={}, restrict_to=None, plot_style=None)[source]

Fits and subtracts the astrophysical background in NIRCam coronagraphic data following the procedure described in Lawson et al. (2024).

Note: This step should only be applied to data that has already been aligned. Otherwise, it will crash.

For SW filters using a LW coronagraph, the field of view excludes the neutral density squares. In this case, the astrophysical background and the artificial background offset that we fit are fully degenerate in the regions we consider (away from the coronagraph). Since SW backgrounds should be low anyway, the default is to assume an astrophysical background of zero here. Alternatively, the JWST Backgrounds Tool can be used to estimate the background for affected data instead (if use_jbt_background=True and the JWST Backgrounds Tool is installed).

Parameters

subdirstr, optional: Name of the sub-directory where the data products will be saved. The default is ‘bgsub’.
mask_snr_thresholdfloat, optional: SNR threshold for features to be masked during fitting of the background. SNR is estimated using the ERR FITS extension. The default is 2.
r_excl_nfwhmfloat, optional: Radius (in units of the effective PSF FWHM) of the region around the star to exclude from the fit. The default is 50.
q_clipfloat, optional: After computing BG model residuals, exclude q_clip% of pixels from both ends of the residual distribution before computing chisq. This is intended to avoid over-/under-estimation of the background due to unmasked sources or artifacts. Default is 5.
align_wrappedbool, optional: Whether input data were aligned using a Fourier shift without padding first (such that values wrapped at the edges). Default is True.
include_global_offsetbool, optional: Whether to fit a uniform background offset along with the astrophysical background model. This corrects for offsets induced by ramp fitting or use of the median subtraction step. Default is True.
include_stellar_psf_componentbool, optional: Whether to include a stellar PSF model component when optimizing the background model. Default is True.
generate_plotbool, optional: Whether to generate a plot showing the data before and after subtraction along with the model and masked residuals. Default is True.
save_modelbool, optional: Whether to save the optimized background model. Default is False.
use_jbt_backgroundbool, optional: Whether to use the JWST Backgrounds Tool to estimate the background surface brightness for data without coverage of ND squares. Requires that jwst_backgrounds is installed. Default is False.
bgmodel_dirstr, optional: Path to the directory containing the normalized background model component FITS files to use (or to which they should be downloaded). If None, uses spaceKLIP/resources/nircam_bg_models/. Default is None.
background_sbdict, optional: A dictionary of fixed background surface brightness (SB) values (in the same units as the data) to adopt for any included concatenation keys. For each key in database.obs, if background_sb[key] is None or if the key is not in background_sb, the background SB will be fit for all observations of that concatenation if possible. Otherwise, background_sb[key] should be an array-like of float or None having the same length as database.obs[key]. If background_sb[key][j] is None, the jth frame’s background SB will be fit, otherwise it will be fixed to the value background_sb[key][j]. Default is {}.
restrict_tostr or None, optional: Restrict the background subtraction to a specific key in the database. Default is None.

update_frames_with_nans_from_nanmask(cval=nan, types=['SCI', 'SCI_BG', 'REF', 'REF_BG'], subdir='nansback')[source]

Replace values in data wiht NaNs from the nanmask.

Parameters

cvalfloat, optional: Fill value for the nan pixels. The default is 0.
typeslist of str, optional: List of data types for which nans shall be replaced. The default is [‘SCI’, ‘SCI_BG’, ‘REF’, ‘REF_BG’].
subdirstr, optional: Name of the directory where the data products shall be saved. The default is ‘nanreplaced’.

Returns

None.

update_miri_offsets()[source]: Updates SCI frame X/Y offsets to zero for older MIRI coronagraphy datasets, and updates REF frame offsets accordingly in FITS headers and the database.

update_nircam_centers(force_siaf_center=False, force_db_center=False)[source]

Checks SIAF PRD version against FITS header PRD version and updates CRPIX if SIAF version is newer. Also accounts for filter-dependent distortion. Might not be required for simulated data.

This step uses lookup tables of information derived from NIRCam commissioning activities CAR-30 and CAR-31, by J. Leisenring and J. Girard, and subsequent reanalyses using additional data from PSF SGD observations.

Parameters

force_siaf_centerbool, optional: Force the use of the SIAF reference pixel position irrespective of versions. The default is False
force_db_centerbool, optional: Force the use of the database reference pixel position irrespective of versions. The default is False

Returns

None.

spaceKLIP.logging_tools module

spaceKLIP.logging_tools.all_logging_disabled(highest_level=50)[source]

A context manager that will prevent any logging messages triggered during the body from being processed.

Usage to suppress levels up to INFO:

>>> with all_logging_disabled(logging.INFO):
>>>     do_something()

Parameters

highest_levelint: The highest logging level that will be let through. Any logging messages at this level or above will be processed as normal. The default is CRITICAL, which will allow only CRITICAL messages through.

spaceKLIP.logging_tools.crds_logging_disabled(highest_level=-3)[source]

A context manager that will prevent any logging messages triggered during the body from being processed.

Usage to suppress levels up to Critical:

>>> with crds_logging_disabled(-3):
>>>     do_something()

Parameters

highest_levelint: For CRDS, logging levels are defined as: -3: CRITICAL -2: ERROR -1: WARNING

0: INFO 1: DEBUG

spaceKLIP.logging_tools.suppress_stdout()[source]: Context manager to suppress stdout

spaceKLIP.mast module

spaceKLIP.mast.download_files(product_table, outputdir='.', verbose=True, **kwargs)[source]

Retrieve data products from MAST

Parameters

product_tableastropy.table: Table of MAST products, as returned by astroquery.Mast
outputdirstr: Directory where to save the output products
verbosebool: Toggle text information output

Other kwargs are passed to get_mast_filename

spaceKLIP.mast.get_mast_filename(filename, outputdir='.', overwrite=False, exists_ok=True, progress=False, verbose=True, mast_api_token=None)[source]

Download any specified filename from MAST, writing to outputdir

If a file exists already, default is to not download. Set overwrite=True to overwrite existing output file. or set exists_ok=False to raise ValueError.

Set progress=True to show a progress bar.

verbose toggles on/off minor informative text output

Other parameters are less likely to be useful: Default mast_api_token comes from MAST_API_TOKEN environment variable.

Adapted from example code originally by Rick White, STScI, via archive help desk.

spaceKLIP.mast.query_coron_datasets(inst, filt=None, mask=None, kind=None, program=None, obsnum=None, channel=None, ignore_cal=True, ignore_ta=True, verbose=False, level=None, ignore_exclusive_access=False, exp_type=None, return_filenames=False)[source]

Query MAST to make a summary table of existing JWST coronagraphic datasets.

Parameters

inststr: ‘NIRCam’ or ‘MIRI’. Required.
filtstr: Filter name, like ‘F356W’. Required.
maskstr: Coronagraph mask name, like ‘MASKA335R’ or ‘4QPM_1550’. Optional. If provided, must exactly match the keyword value as used in MAST, which isn’t always what you might expect. In particular, you need to explicitly include the “A” for the NIRCam A module in e.g., ‘MASKA335R’.
kindstr: ‘SCI’ for science targets, ‘REF’ for PSF references, or ‘BKG’ for backgrounds.
channelstr: For NIRCam only, channel name, “SW” or “SHORT” versus “LW” or “LONG”. Leave blank for both.
ignore_tabool: Ignore/exclude any target acquisition exposures. This can be useful to only include science and reference images.
ignore_calbool: Ignore/exclude any category=’CAL’ calibration programs. This can be desirable to ignore the NIRCam coronagraphic flux calibration data sets, which otherwise look like science data to this query (programs 1537 and 1538 for example).
exp_typelist of strings, or None: By default, the value for the MAST query field on exposure type is determined automatically, based on whether or not ignore_ta is set. Set this optional parameter if you want to control the exp_type value used in the query directly.
ignore_exclusive_accessbool: Whether or not to ignore (filter out from query results) any data which is still under exclusive access restrictions to the original proposing team. For example, query for kind=’REF’, ignore_exclusive_access=True to find only the publicly-available PSF references that can be downloaded by anyone.
return_filenamesbool: Return a shorter summary table of observations, versus returning a more comprehensive longer table of individual exposures and filenames?
levelstr: Desired JWST data product level for filenames. ‘1b’ or ‘uncal’, ‘2a’ or ‘rate’, etc. For historical reasons it’s not possible to easily query MAST directly for products earlier than level 2b (cal/calints); MAST “hides” lower level files once higher level products are available. Thus this works by querying for the level 2b products, and performing filename transformation on them

Returns

None.

spaceKLIP.mast.set_params(parameters)[source]: Utility function for making dicts used in MAST queries.

spaceKLIP.plotting module

spaceKLIP.plotting.annotate_compass(ax, image, wcs, xf=0.9, yf=0.1, length_fraction=0.07, color='white', bbox_color='#4B0082', fontsize=12)[source]

Plot a compass annotation onto an image, indicating the directions of North and East.

Makes use of the methods from jdaviz, but positions the compass differently: jdaviz defaults to putting it in the center, and filling most of the image. Here we want to make a small compass in the corner.

Parameters

axmatplotlib.Axes: The axis on which to draw the compass annotation.
imagendarray: A 2D image to be annotated (used just to get the image dimensions).
wcsastropy.wcs.WCS: World Coordinate System (WCS) information.
xf, yffloat, optional: The horizontal (xf) and vertical (yf) positions of the compass as fractions of the image width and height, respectively. Values should be between 0 and 1, where 0 places the compass at the left or bottom edge, and 1 places it at the right or top edge. Default is (0.9, 0.1), placing the compass near the bottom-right corner.
length_fractionfloat, optional: Length of the compass, as a fraction of the size of the entire image
colorstr, optional: The color of the compass arrows and labels. Default is ‘white’.
bbox_colorstr, optional: The background color for the text labels (‘N’ and ‘E’). Default is ‘#4B0082’. If set to None, no background box will be drawn.
fontsizeint, optional: The font size for the compass labels. Default is 12.

Returns

None.

spaceKLIP.plotting.annotate_scale_bar(ax, image, wcs, length=<Quantity 1. arcsec>, xf=0.1, yf=0.1, color='white', bbox_color='#4B0082', lw=3, fontsize=10)[source]

Plot a scale bar on an image.

Parameters

axmatplotlib.Axes: The axis on which to draw the scale bar.
imagendarray: The 2D image to be annotated (used just to get the image dimensions).
wcsastropy.wcs.WCS: World Coordinate System (WCS) information.
lengthastropy.Quantity, optional: Length of the scale bar, in arcsec or equivalent unit
xf, yffloat, optional: The horizontal (xf) and vertical (yf) positions of the compass as fractions of the image width and height, respectively. Values should be between 0 and 1, where 0 places the compass at the left or bottom edge, and 1 places it at the right or top edge. Default is (0.9, 0.1), placing the compass near the bottom-right corner.
colorstr, optional: The color of the scale bar and the text label. Default is ‘white’.
bbox_colorstr, optional: The background color for the text label. Default is ‘#4B0082’. If set to None, no background box will be drawn.
lwfloat, optional: The line width of the scale bar. Default is 3.
fontsizeint, optional: The font size of the text label displaying the scale bar length. Default is 10.

Returns

None.

spaceKLIP.plotting.annotate_secondary_axes_arcsec(ax, image, wcs)[source]

Update an image display to add secondary axes labels in an arcsec.

Parameters

axmatplotlib.Axes: The axis on which to add secondary axes labels.
imagendarray: The 2D image to be annotated (used just to get the image dimensions).
wcsastropy.wcs.WCS: World Coordinate System (WCS) information.

Returns

None.

spaceKLIP.plotting.compModern(size=20)[source]

spaceKLIP.plotting.compare_clean_methods(files, kwargs_list=None, zoom_region=None, interactive=False)[source]

Plot and compare spaceKLIP clean methods. For the Bad Pixel Tutorial Notebook.

Parameters

fileslist of str: FITS files containing cleaned products.
kwargs_listlist of dict: List of parameter dictionaries corresponding to each run.
zoom_regiontuple, optional: (x0, x1, y0, y1) zoom region.

Returns

None.

spaceKLIP.plotting.compare_find_methods(files, kwargs_list=None, zoom_region=None, interactive=True)[source]

Plot and compare bad-pixel masks from multiple runs on a given image. For the Bad Pixel Tutorial Notebook.

Parameters

fileslist of str: FITS files containing DQ and science data.
kwargs_listlist of dict, optional: Parameter dictionaries corresponding to each run.
zoom_regiontuple, optional: (x0, x1, y0, y1) zoom region.
interactivebool, optional: Interactive Plotly plot or static Matplotlib plot. Default is True.

Returns

None

spaceKLIP.plotting.display_coron_dataset(database, restrict_to=None, save_filename=None, stage3=None, vmin=None, vmax=None, stretch=0.0001, zoom_center=3, dq_only=False, interactive=False, bbox_color='#4B0082', plot_style=None)[source]

Display multiple files in a coronagraphic dataset.

Parameters

databasespaceklip.Database

Database of files to plot.

restrict_tostr or dict, optional

Optional query to filter and display specific data.

None: No filtering; all tables are processed.
str: Only datasets whose database concatenation (file group) name includes this string will be shown. Most simply, set this to a filter name to only plot images with that filter.
dict: Filters tables based on database column values, where keys are column names and values are filter criteria.

stage3str, optional

Specify if data is stage 3.

save_filenamestr

If provided, the plots will be saved to a PDF file with this name.

vmin, vmaxfloat, optional

The minimum/maximum data value to use for scaling the image. If None, determined automatically.

stretchfloat, optional

The stretch factor for the asinh normalization. If None, defaults to 0.0001.

zoom_centerint, optional

The zoom factor for the inset axis centered on the image’s center. Set to None to disable.

dq_onlybool, optional

If True, only the DO_NOT_USE DQ flags are displayed, not the image data itself.

interactivebool, optional

If True, the plots will be displayed interactively.

bbox_colorstr, optional

The background color for the text label. Default is ‘#4B0082’. If set to None, no background box will be drawn.

Returns

None.

spaceKLIP.plotting.display_coron_image(filename, vmin=None, vmax=None, stretch=0.0001, bbox_color='#4B0082', dq_only=False, zoom_center=3, ax=None, plot_style=None)[source]

Display and annotate a coronagraphic image.

Shows image on asinh scale along with some basic metadata, scale bar, and compass. Optionally, a zoomed inset around the image center can be displayed.

This display function is designed to flexibly adapt to several different kinds of input data, including rate, rateints, cal, calints files. And pyKLIP’s KLmode cubes.

Parameters

filenamestr: The path to the file containing the image data.
vmin, vmaxfloat, optional: The minimum/maximum data value to use for scaling the image. If None, determined automatically.
stretchfloat, optional: The stretch factor for the asinh normalization. If None, defaults to 0.0001.
bbox_colorstr, optional: The background color for the text label. Default is ‘#4B0082’. If set to None, no background box will be drawn.
dq_onlybool, optional: If True, only the DO_NOT_USE DQ flags are displayed, not the image data itself.
zoom_centerint, optional: The zoom factor for the inset axis centered on the image’s center. Set to None to disable.

Returns

None.

spaceKLIP.plotting.display_image_comparisons(database, base_dirs, restrict_to=None, save_filename=None, vmin=None, vmax=None, stretch=0.0001, zoom_center=None, interactive=False, dq_only=False, subtract_first=False, plot_style=None)[source]

Compare images before and after processing.

Parameters

databasespaceklip.Database

Database of files to plot.

base_dirslist of str

List of base directory names.

restrict_tostr or dict, optional

Optional query to filter and display specific data.

None: No filtering; all tables are processed.
str: Only datasets whose database concatenation (file group) name includes this string will be shown.
Most simply, set this to a filter name to only plot images with that filter.
dict: Filters tables based on database column values, where keys are column names and values are filter criteria.

save_filenamestr

If provided, the plots will be saved to a PDF file with this name.

vmin, vmaxfloat, optional

The minimum/maximum data value to use for scaling the image. If None, determined automatically.

stretchfloat, optional

The stretch factor for the asinh normalization. If None, defaults to 0.0001.

zoom_centerint, optional

The zoom factor for the inset axis centered on the image’s center. Set to None to disable.

dq_onlybool, optional

If True, only the DO_NOT_USE DQ flags are displayed, not the image data itself.

subtract_firstbool

Whether to subtract the first SCI frame from subsequent frames.

interactivebool, optional

If True, the plots will be displayed interactively.

Returns

None.

spaceKLIP.plotting.load_plt_style(style=None)[source]

Load the matplotlib style for spaceKLIP plots.

Load the style sheet (default of sk_style.mplstyle), which is a modified version of the style sheet from the webbpsf_ext package.

spaceKLIP.plotting.plot_chains(chain, savefile)[source]: Plot MCMC chains from companion fitting

spaceKLIP.plotting.plot_contrast_calibrated(thrput, med_thrput, fit_thrput, con_seps, cons, corr_cons, savefile='./calcontrast.pdf', plot_style=None)[source]: Plot calibrated throughput alongside calibrated contrast curves.

spaceKLIP.plotting.plot_contrast_images(meta, data, data_masked, pxsc=None, savefile='./maskimage.pdf', plot_style=None)[source]: Plot subtracted images to be used for contrast estimation, one with companions marked, one with the masking adopted.

spaceKLIP.plotting.plot_contrast_raw(meta, seps, cons, labels='default', savefile='./rawcontrast.pdf', plot_style=None)[source]: Plot raw contrast curves for different KL modes.

spaceKLIP.plotting.plot_fm_psf(meta, fm_frame, data_frame, guess_flux, pxsc=None, j=0, savefile='./fmpsf.pdf', plot_style=None)[source]: Plot forward model psf

spaceKLIP.plotting.plot_injected_locs(meta, data, transmission, seps, pas, pxsc=None, savefile='./injected.pdf', plot_style=None)[source]: Plot subtracted image and 2D transmission alongside locations of injected planets.

spaceKLIP.plotting.plot_subimages(imgdirs, subdirs, filts, submodes, numKL, window_size=2.5, cmaps_list=['viridis'], imgVmin=[-40], imgVmax=[40], subVmin=[-10], subVmax=[10], labelpos=[0.04, 0.05], imtext_col='w', showKL=True, useticklabels=True, cbar_textoff=1, hspace=0.05, wspace=0.05, plot_style=None)[source]

Create a “publication ready” plot of the coronagraphic images, alongside the PSF subtracted images. A grid of images will be made. Rows will correspond to filters, first column the unsubtracted PSF, following columns different submodes and numKLs

Parameters

imgdirslist of strings: Parent directories of the unsubtracted images, filters won’t be repeated
subdirslist of strings: Parent directories of the subtracted images
filtslist of strings: List of filter strings to include in the plot
submodeslist of strings: ‘ADI’, ‘RDI’, ‘RDI+ADI’ (or ‘ADI+RDI’)
numKLlist of ints: output images are 3-D with the third axis corresponding to different KL modes used in subtraction. Indicate the number of KL modes you want to display, if more than one, display each for each submode on the same row .
window_sizefloat: the number of arcseconds on a side
cmaps_listlist: a list of strings naming the colormaps for each filter. If len(cmaps_list)==1 the same cmap will be used for each filter.
imgVminlist: a list of the min values for the the cmaps for each filter. if len(imgVmin)==1 the same min value will be used for each filter.
imgVmaxlist: a list of the max values for the the cmaps for each filter. if len(imgVmax)==1 the same max value will be used for each filter.
subVminlist: a list of the min values for the the subtracted image cmaps for each filter. if len(imgVmin)==1 the same min value will be used for each filter.
subVmaxlist: a list of the max values for the the subtracted image cmaps for each filter. if len(imgVmin)==1 the same min value will be used for each filter.
labelpos: list: Position of the [RA, Dec] axis labels (figure coords)
imtext_col: str: Color of any text / arrows that go on top of the images

spaceKLIP.plotting.set_default_style(style)[source]: Adjust the default matplotlib style for spaceKLIP plots.

spaceKLIP.plotting.tickFont(ax, xy, fontproperties)[source]

spaceKLIP.psf module

class spaceKLIP.psf.JWST_PSF(apername, filt, date=None, fov_pix=65, oversample=2, sp=None, use_coeff=False, **kwargs)[source]

Bases: object

Create coronagraphic PSFs for JWST NIRCam and MIRI

This object provides the ability to generate a synthetic NIRCam coronagraphic PSF using webbpsf and webbpsf_ext at an arbitrary location relative to the occulting mask, taking into account mask attenuation near the IWA.

There are multiple ways to estimate these PSFs:

extrapolation from the theoretical occulting mask transmission (fastest)
webbpsf_ext PSF coefficients (intermediate speed)
on-the-fly calculations with webbpsf (slowest, but most accurate).

Includes the ability to use date-specific OPD maps as generated by the JWST wavefront sensing group. Simply set use_coeff=False, and supply a date in ISO format.

NOTE: By default, resulting PSFs were normalized such that their total intensity is 1.0 at the telescope entrance pupil (e.g., normalize=’first’). So, the final intensity of these PSFs include throughput attenuation at intermediate optics such as the NIRCam Lyot stops and occulting masks. During PSF generation, set normalize=’exit_pupil’ for PSFs that have are normalized to 1.0 when summed out to infinity. Only works for quick=False.

property bandpass

property filter

property fov_pix

gen_psf(loc, mode='xy', PA_V3=0, return_oversample=False, do_shift=True, addV3Yidl=True, normalize='first', **kwargs)[source]

Generate offset PSF rotated by PA to N-E orientation.

Generate a PSF for some (x,y) detector position in N-E sky orientation.

Parameters

locfloat or ndarray

(x,y) or (r,th) location (in arcsec) offset from center of mask.

PA_V3float

V3 PA of ref point N over E (e.g. ‘ROLL_REF’). Will add ‘V3IdlYAngle’.

return_oversamplebool

Return the oversampled version of the PSF?

do_shiftbool

If True, will offset PSF by some amount from center. Otherwise, returns PSF in center of image.

addV3Yidlbool

Add V3IdlYAngle to PA_V3 when converting (r,th) to (x,y) in idl coords? This assumes that (r,th) are not already in idl coords, but are instead relative to North / East sky coordinates.

normalizestr

How to normalize the PSF. Options are:

‘first’: Normalize to 1.0 at entrance pupil
‘exit_pupil’: Normalize to 1.0 at exit pupil

Only works for quick=False.

Keyword Args

quickbool: Use linear combination of on-axis and off-axis PSFs to generate PSF as a function of corongraphic mask throughput. Typically takes 10s of msec, compared to standard calculations using coefficients (~1 sec) or on-the-fly calcs w/ webbpsf (10s of sec). Only applicable for NIRCam.
spwebbpsf_ext.synphot_ext.Spectrum: Manually specify spectrum to get a desired wavelength weighting. Only applicable if quick=False. If not set, defaults to self.sp.

Returns

None.

gen_psf_idl(coord_vals, coord_frame='idl', quick=True, sp=None, return_oversample=False, do_shift=False, normalize='first')[source]

Generate offset PSF in detector frame.

Generate a PSF with some (x,y) position in some coordinate frame (default idl).

Parameters

coord_valstuple or None

Coordinates (in arcsec or pixels) to calculate field-dependent PSF. If multiple values, then this should be an array ([xvals], [yvals]).

coord_framestr

Type of input coordinates. Default is ‘idl’.

‘tel’: arcsecs V2,V3
‘sci’: pixels, in DMS axes orientation; aperture-dependent
‘det’: pixels, in raw detector read out axes orientation
‘idl’: arcsecs relative to aperture reference location.

quickbool

Use linear combination of on-axis and off-axis PSFs to generate PSF as a function of corongraphic mask throughput. Typically takes 10s of msec, compared to standard calculations using coefficients (~1 sec) or on-the-fly calcs w/ webbpsf (10s of sec). Only applicable for NIRCam.

spwebbpsf_ext.synphot_ext.Spectrum

Manually specify spectrum to get a desired wavelength weighting. Only applicable if quick=False. If not set, defaults to self.sp.

return_oversamplebool

Return the oversampled version of the PSF?

do_shiftbool

If True, will return the PSF offset from center in ‘idl’ coords. Otherwise, returns PSF in center of image.

normalizestr

How to normalize the PSF. Options are:

‘first’: Normalize to 1.0 at entrance pupil
‘exit_pupil’: Normalize to 1.0 at exit pupil

Only works for quick=False.

Returns

None.

property image_mask

property name

property oversample

property pupil_mask

rth_to_xy(r, th, PA_V3=0, frame_out='idl', addV3Yidl=True)[source]

Convert (r,th) location to (x,y) in idl coords.

Assume (r,th) in coordinate system with North up East to the left. Then convert to NIRCam detector orientation (idl coord frame). Units assumed to be in arcsec.

Parameters

rfloat or ndarray

Radial offst from mask center.

thfloat or ndarray

Position angle (positive angles East of North) in degrees. Can also be an array; must match size of r.

PA_V3float

V3 PA of ref point N over E (e.g. ‘ROLL_REF’).

frame_outstr

Coordinate frame of output. Default is ‘idl’.

‘tel’: arcsecs V2,V3
‘sci’: pixels, in DMS axes orientation; aperture-dependent
‘det’: pixels, in raw detector read out axes orientation
‘idl’: arcsecs relative to aperture reference location.

Returns

None.

property use_coeff

spaceKLIP.psf.gen_offsetpsf(obs, xyoff=None, date=None, source=None)[source]

Generate a WebbPSF model PSF. The total intensity will be normalized to 1.

Parameters

obsastropy table: Concatenation of a spaceKLIP observations database for which the model PSF shall be computed.
xyofftuple, optional: Offset (arcsec) from coronagraphic mask center in detector coordinates to generate position-dependent PSF. The default is None.
datestr, optional: Observation date in the format ‘YYYY-MM-DDTHH:MM:SS.MMM’. Will query for the wavefront measurement closest in time before the given date. If None, then the default WebbPSF OPD is used (RevAA). The default is None.
sourcesynphot.spectrum.SourceSpectrum, optional: Defaults to a 5700 K blackbody. The default is None.

Returns

offsetpsf2D-array: WebbPSF model PSF.

spaceKLIP.psf.get_offsetpsf(obs, recenter=True, derotate=True)[source]

Compute a derotated and integration time weighted average of a WebbPSF model PSF.

Parameters

obsastropy table: Concatenation of a spaceKLIP observations database for which the derotated and integration time weighted average of the model PSF shall be computed.
recenterbool, optional: Recenter the model PSF? The offset PSF from WebbPSF is not properly centered because the wedge mirror that folds the light onto the coronagraphic subarrays introduces a chromatic shift. The default is True.
derotatebool, optional: Derotate and integration time weigh the model PSF? The default is True.

Returns

totpsf2D-array: Derotated and integration time weighted average of the model PSF.

spaceKLIP.psf.get_transmission(obs)[source]

Compute a derotated and integration time weighted average of the transmission mask.

Parameters

obsastropy table: Concatenation of a spaceKLIP observations database for which the derotated and integration time weighted average of the transmission mask shall be computed.

Returns

totmsk2D-array: Derotated and integration time weighted average of the transmission mask.

spaceKLIP.psf.recenter_jens(image)[source]

Find the shift that centers a PSF on its nearest pixel by maximizing its peak count.

Parameters

image2D-array: Input image to be recentered.

Returns

shift1D-array: X- and y-shift that centers the PSF.

spaceKLIP.psflib module

spaceKLIP.psflib.adjust_spttype(spt_tup)[source]

spaceKLIP.psflib.build_refdb(idir, odir='.', suffix='calints', overwrite=False, prefer_SIMBAD=True)[source]

Constructs a database of target-specific reference info for each calints file in the input directory.

Args:

idir (str or list): Path to directory containing JWST images, or list of: individual file paths, to construct the database from.

odir (path, optional): Location to save the database. Defaults to ‘.’. suffix (str, optional): Input filename suffix, e.g. ‘uncal’ or ‘calints’.

Defaults to ‘calints’. Does not apply if list of fpaths is provided to idir.

overwrite (bool, optional): If true, overwrite the existing caldb. prefer_SIMBAD (bool, optional): Default to choosing database info SIMBAD as opposed to MOCA

database. Defaults to True.

Returns:

pandas.DataFrame: database containing target- and observation-specific: info for each file.

spaceKLIP.psflib.decode_simbad_sptype(input_sptypes)[source]

Decodes the complicated SIMBAD spectral type string into simplified spectral type components.

Args:

input_sptypes (str or list): SIMBAD spectral type string (or list of strings)

Returns:

tuple: list of spectral class letters, list of subclass numbers,: and list of luminosity class numerals for each input string.

spaceKLIP.psflib.download_mast(ref_db, token=None, overwrite=False, exists_ok=True, progress=False, verbose=False, suffix=None, base_dir='DATA/MAST_DOWNLOAD')[source]

Given the reference database, downloads MAST data for each file to base_dir. If a file exists already, default is to not download. Set overwrite=True to overwrite existing output file. or set exists_ok=False to raise ValueError.

Set progress=True to show a progress bar.

Args:: ref_db (pandas.DataFrame): The reference database token (str, optional): MAST token. Default is to reference the environment

variable MAST_API_TOKEN.

spaceKLIP.psflib.get_sciref_files(sci_target, refdb, idir=None, spt_tolerance=None, filters=None, exclude_disks=False)[source]

Construct a list of science files and reference files to input to a PSF subtraction routine.

Args:

sci_target (str):: name of the science target to be PSF subtracted. Can be the proposal target name, JWST resolved target name, or 2MASS ID.
refdb (pandas.DataFrame or str):: pandas dataframe or filepath to csv containing the reference database generated by the build_refdb() function.
idir (str):: path to directory of input data, to be appended to file names.
spt_tolerance (str or int, optional):: None (default): use all spectral types. ‘exact’ : use only refs with the exact same spectral type. ‘class’ : use only references with the same spectral class letter. ‘subclass’ : use only references with the same spectral class letter and subclass number. (ignores luminosity class) int : use only refs within +- N spectral subclasses, e.g. M3-5 for an M4 science target if spt_tolerance = 1.
filters (str or list, optional):: None (default) : include all filters. ‘F444W’ or other filter name: include only that filter. [‘filt1’,’filt2’]: include only filt1 and filt2

exclude_disks (bool, optional): Exclude references that are known to have disks. Defaults to False.

Returns:

list: filenames of science observations. list: filenames of reference observations.

spaceKLIP.psflib.isnone(series)[source]

Helper function to determine which elements of a series are NaN, None, or empty strings.

Args:: series (list-like): input data to check
Returns:: boolean array: True values where input array is NaN/None/’’

spaceKLIP.psflib.load_refdb(fpath)[source]

Reads the database of target- and observation-specific reference info for each observation in the PSF library.

Args:

fpath (str or os.path): Path to the .csv file containing the reference: database.

Returns:

pandas.DataFrame: database containing target- and observation-specific: info for each file.

spaceKLIP.psflib.not_isnone(series)[source]

spaceKLIP.psflib.update_db_sptypes(refdb)[source]

Separate the spectral type column into a column each for the spectral class letter, subclass number, and luminosity class numeral.

Args:: refdb (pandas.DataFrame): PSF reference dataframe
Returns:: pandas.DataFrame: updated PSF reference dataframe

spaceKLIP.pyklippipeline module

spaceKLIP.pyklippipeline.get_pyklip_filepaths(database, key, return_maxbasis=False)[source]

Quick wrapper function to get the filepath information (in addition to the maxnumbasis) for pyKLIP from a spaceKLIP database.

Parameters

databasespaceKLIP.Database: SpaceKLIP database on which pyKLIP shall be run.
keystr: Key for the concatenation of interest in the spaceKLIP database
return_maxbasisbool, optional: Toggle for whether to additionally return the maximum number of basis vectors.

Returns

filepaths1D-array: List of science image file names
psflib_filepaths1D-array: List of reference image file names
maxnumbasisint, optional: The maximum number of basis vectors available.

spaceKLIP.pyklippipeline.run_obs(database, restrict_to=None, kwargs={}, subdir='klipsub')[source]

Run pyKLIP on the input observations database.

Parameters

databasespaceKLIP.Database

SpaceKLIP database on which pyKLIP shall be run.

kwargsdict, optional

Keyword arguments for the pyklip.parallelized.klip_dataset method. Available keywords are:

modelist of str, optional
Subtraction modes that shall be looped over. Possible values are ‘ADI’, ‘RDI’, and ‘ADI+RDI’. The default is [‘ADI+RDI’].
annulilist of int, optional
Numbers of subtraction annuli that shall be looped over. The default is [1].
subsectionslist of int, optional
Numbers of subtraction subsections that shall be looped over. The default is [1].
numbasislist of int, optional
Number of KL modes that shall be looped over. The default is [1, 2, 5, 10, 20, 50, 100].
movementfloat, optional
Minimum amount of movement (pix) of an astrophysical source to consider using that image as a reference PSF. The default is 1.
verbosebool, optional
Verbose mode? The default is False.
save_rollsbool, optional
Save each processed roll separately? The default is False.
save_full_outputbool, optional
Save the full output cube before flattening? The default is False.

The default is {}.

subdirstr, optional

Name of the directory where the data products shall be saved. The default is ‘klipsub’.

Returns

None.

spaceKLIP.starphot module

spaceKLIP.starphot.get_stellar_magnitudes(starfile, spectral_type, instrume, detector, exp_type, output_dir=None, plot_style=None, **kwargs)[source]

Get the source brightness and zero point fluxes in each filter of the JWST instrument in use, using per-detector PCE data.

Parameters

starfilepath: Path of VizieR VOTable containing host star photometry or two column TXT file with wavelength (micron) and flux (Jy).
spectral_typestr, optional: Host star spectral type for the stellar model SED. The default is ‘G2V’.
instrume‘NIRCAM’ or ‘MIRI’: JWST instrument in use.
detectorstr: Detector name (e.g. ‘NRCALONG’, ‘NRCA1’, ‘MIRIMAGE’).
exp_typestr: Exposure type from the FITS header (e.g. ‘NRC_CORON’, ‘NRC_IMAGE’, ‘MIR_4QPM’, ‘MIR_LYOT’, ‘MIR_IMAGE’).
output_dirpath, optional: Path of the directory where the SED plot shall be saved. The default is None.

Keyword Args

Tefffloat: Effective temperature ranging from 3500K to 30000K.
metallicityfloat: Metallicity [Fe/H] value ranging from -2.5 to 0.5.
log_gfloat: Surface gravity (log g) from 0 to 5.
Avfloat: Add extinction to the stellar spectrum
catnamestr: Catalog name, including ‘bosz’, ‘ck04models’, and ‘phoenix’. Default is ‘bosz’, which comes from BOSZ_spectrum().
resstr: Spectral resolution to use (200 or 2000 or 20000).
interpolatebool: Interpolate spectrum using a weighted average of grid points surrounding the desired input parameters. Default: True
radiusfloat: Search radius in arcseconds for Vizier query. Default: 1 arcsec.

Returns

mstardict: Dictionary of the source brightness (vegamag) in each filter of the JWST instrument in use.
fzerodict: Dictionary of the zero point flux (Jy) of each filter of the JWST instrument in use.
fzero_flamdict: Dictionary of the zero point flux (erg/s/cm^2/A) of each filter of the JWST instrument in use.
fzero_wm2umdict: Dictionary of the zero point flux (W/m^2/um) of each filter of the JWST instrument in use.

spaceKLIP.starphot.read_spec_file(starfile)[source]

Read a spectrum from a TXT file.

Parameters

starfilepath: Path of two column TXT file with wavelength (micron) and flux (Jy).

Returns

sedsynphot.SourceSpectrum: Spectrum of the source.

spaceKLIP.starphot.read_votable(starfile, spectral_type, instrume, output_dir, plot_style, **kwargs)[source]

Read a spectrum from a VOTable file.

Parameters

starfilepath: Path of VizieR VOTable containing host star photometry.
spectral_typestr: Host star spectral type for the stellar model SED.
instrume‘NIRCAM’ or ‘MIRI’: JWST instrument in use.
output_dirpath, optional: Path of the directory where the SED plot shall be saved. The default is None.
plot_stylestr, optional: Matplotlib style to use for the SED plot. The default is None.

Returns

sedsynphot.SourceSpectrum: Spectrum of the source.

spaceKLIP.utils module

spaceKLIP.utils.alignlsq(shift, image, ref_image, mask=None, method='fourier', kwargs={})[source]

Align an image to a reference image using a Fourier shift and subtract method.

Parameters

shift1D-array: X- and y-shift and scaling factor to be applied.
image2D-array: Input image to be aligned to a reference image.
ref_image2D-array: Reference image.
mask2D-array, optional: Weights to be applied to the input and reference images. The default is None.
method‘fourier’ or ‘spline’ (not recommended), optional: Method for shifting the frames. The default is ‘fourier’.
kwargsdict, optional: Keyword arguments for the scipy.ndimage.shift routine. The default is {}.

Returns

imres1D-array: Residual image collapsed into one dimension.

spaceKLIP.utils.bg_minimize(par, X, Y, bgmaskfile)[source]

Simple minimisation function for Godoy background subtraction

Parameters

parint: Variable to scale background array
Xndarray: Science / reference image
Yndarray: Background image
bgmaskfilestr: File which provides a mask to select which pixels to compare during minimisation

Returns

Sum of the squares of the residuals between images X and Y.

spaceKLIP.utils.chisqr_red(yvals, yfit=None, err=None, dof=None, err_func=<function std>)[source]

Calculate reduced chi square metric

If yfit is None, then yvals assumed to be residuals. In this case, err should be specified.

Parameters

yvalsndarray: Sampled values.
yfitndarray: Model fit corresponding to yvals.
dofint: Number of degrees of freedom (nvals - nparams - 1).
errndarray or float: Uncertainties associated with yvals. If not specified, then use yvals point-to-point differences to estimate a single value for the uncertainty.
err_funcfunc: Error function uses to estimate err.

spaceKLIP.utils.config_stpipe_log(level='WARNING', suppress=False)[source]

Configure the logging level for the stpipe pipeline.

Parameters

levelstr: The logging level as a string (e.g., ‘ERROR’, ‘DEBUG’).
suppressbool: If True, suppresses the log output to ERROR level. If False, restores the default logging configuration.

Returns

None.

spaceKLIP.utils.crop_image(image, xycen, npix, return_indices=False)[source]

Crop an image.

Parameters

image2D-array: Input image to be cropped.
xycentuple of float: Center around which the image shall be cropped. Will be rounded.
npixfloat: Size of the cropped image. Will be rounded.
return_indicesbool, optional: If True, returns the x- and y-indices of the cropped image in the coordinate frame of the input image. The default is False.

Returns

imsub2D-array: The cropped image.
xsub_indarr1D-array, optional: The x-indices of the cropped image in the coordinate frame of the input image.
ysub_indarr1D-array, optional: The y-indices of the cropped image in the coordinate frame of the input image.

spaceKLIP.utils.cube_fit(tarr, data, sat_vals, sat_frac=0.95, bias=None, deg=1, bpmask_arr=None, fit_zero=False, verbose=False, use_legendre=False, lxmap=None, return_lxmap=False, return_chired=False)[source]: Fit unsaturated data and return coefficients

spaceKLIP.utils.cube_outlier_detection(data, sigma_cut=10, nint_min=10)[source]

Get outlier pixels in a cube model (e.g., rateints or calints)

Parameters

datandarray: Data array to use for outlier detection. Must be a cube with shape (nint, ny, nx).

Keyword Args

sigma_cutfloat: Sigma cut for outlier detection. Default is 5.
nint_minint: Minimum number of integrations required for outlier detection. Default is 5.

Returns

Mask of bad pixels with same shape as input cube.

spaceKLIP.utils.estimate_padding_for_shift(align_shift, center_shift)[source]

spaceKLIP.utils.gaussian_kernel(sigma_x=1, sigma_y=1, theta_degrees=0, n=6)[source]

Generates a 2D Gaussian kernel with specified standard deviations and rotation.

Parameters: sigma_x (float): Standard deviation of the Gaussian in the x direction. sigma_y (float): Standard deviation of the Gaussian in the y direction. theta_degrees (float): Rotation angle of the Gaussian kernel in degrees.

Returns: numpy.ndarray: The generated Gaussian kernel.

spaceKLIP.utils.get_dqmask(dqarr, bitvalues, return_bool=False)[source]

Get DQ mask from DQ array.

Given some DQ array and a list of bit values, return a filtered bit mask for the pixels that have the specified bit values.

To get a bad pixel mask of certain types, for instance:: bp_mask = get_dqmask(dq, [‘SATURATED’, ‘JUMP_DET’, ‘RC’]) > 0

Parameters

dqarrndarray: DQ array. Either 2D or 3D.
bitvalueslist: List of bit values or mnemonics to use for DQ mask. Numbered values must be powers of 2 (e.g., 1, 2, 4, 8, 16, …), representing the specific DQ bit flags.
return_boolbool: If True, return a boolean mask instead of an integer DQ mask. Returns a boolean pixel mask showing which pixels have any of the specified bit values set.

Returns

ndarray: DQ mask with only requested bit values set to True.

spaceKLIP.utils.get_filter_info(instrument, timeout=1, do_svo=False, return_more=False)[source]

Load filter information from the SVO Filter Profile Service or webbpsf.

Deprecated since version This: function is deprecated. Use get_pce_info() instead, which provides per-detector filter information from the consolidated PCE data.

Load NIRCam, NIRISS, and MIRI filters from the SVO Filter Profile Service. http://svo2.cab.inta-csic.es/theory/fps/

If timeout to server, then use local copy of filter list and load through STPSF.

Parameters

instrumentstr: Name of instrument to load filter list for. Must be one of ‘NIRCam’, ‘NIRISS’, or ‘MIRI’.
timeoutfloat: Timeout in seconds for connection to SVO Filter Profile Service.
do_svobool: If True, try to load filter list from SVO Filter Profile Service. If False, use STPSF without first check web server.
return_morebool: If True, also return do_svo variable, whether SVO was used or not.

spaceKLIP.utils.get_nrcmask_from_apname(apname)[source]

Get mask name from aperture name.

The aperture name is of the form: NRC[A/B][1-5]_[FULL]_[MASK]_[FILTER] where MASK is the name of the coronagraphic mask used.

For target acquisition apertures the mask name can be prependend with “TA” (eg., TAMASK335R).

Return ‘NONE’ if MASK not in input aperture name.

Parameters

apnamestr: String aperture name as described above

Returns

image_maskstr: String for image mask

spaceKLIP.utils.get_pce_info(instrume, filt, detector, exp_type)[source]

Look up PCE data and filter metadata for a given instrument, filter, detector, and exposure type combination.

The observing mode is resolved automatically from the exposure type and detector name:

NIRCam: ‘coronagraphy’ if exp_type == ‘NRC_CORON’,
‘lw_imaging’ if detector in (‘NRCALONG’, ‘NRCBLONG’), ‘sw_imaging’ otherwise.

MIRI: ‘coronagraphy’ if exp_type in (‘MIR_4QPM’, ‘MIR_LYOT’),
‘imaging’ otherwise.

Parameters

instrumestr: Instrument name (e.g. ‘NIRCAM’, ‘MIRI’).
filtstr: Filter name (e.g. ‘F356W’, ‘F1065C’).
detectorstr: Detector name (e.g. ‘NRCALONG’, ‘NRCA1’, ‘MIRIMAGE’).
exp_typestr: Exposure type from the FITS header (e.g. ‘NRC_CORON’, ‘NRC_IMAGE’, ‘MIR_4QPM’, ‘MIR_LYOT’, ‘MIR_IMAGE’).

Returns

infodict: Dictionary with keys: ‘wavelengths’, ‘pce’, ‘WavelengthMean’, ‘WavelengthPivot’, ‘WidthEff’, ‘ZeroPointJy’, ‘ZeroPointFlam’, ‘ZeroPointWm2um’. Wavelengths and widths are in Angstrom, zero points in their respective units.

Raises

KeyError: If the requested combination is not found in the PCE data.

spaceKLIP.utils.get_siaf(inst)[source]

Simple wrapper for SIAF (Science Instrument Aperture File) load, with caching for speed because it takes like 0.2 seconds per instance to load this.

Parameters

inststr: The name of the instrument for which to load the SIAF.

Returns

pysiaf.Siaf: The loaded SIAF object for the specified instrument.

spaceKLIP.utils.get_tp_comsubst(instrume, subarray, filt)[source]

Get the COM substrate transmission averaged over the respective filter profile.

TODO: Spot check the COM throughput using photometric calibration data, assuming there are stellar offsets on and off the COM substrate.

Parameters

instrume‘NIRCAM’, ‘NIRISS’, or ‘MIRI’: JWST instrument in use.
subarraystr: JWST subarray in use.
filtstr: JWST filter in use.

Returns

tp_comsubstfloat: COM substrate transmission averaged over the respective filter profile

spaceKLIP.utils.get_visitid(visitstr)[source]

Common util function to handle several various kinds of visit specifications.

Parameters

visitstrstr: The visit string in one of the following formats: - Standard visit ID starting with “V” (e.g., “V0450331001”) - PPS format visit ID with colon-separated parts (e.g., “4503:31:1”)

Returns

str: The standardized visit ID starting with “V” (e.g., “V0450331001”).

spaceKLIP.utils.imshift(image, shift, pad=True, pad_amount=5, nan_reflected=True, crop_after_pad=False, method='fourier', kwargs={})[source]

Shift an image.

Parameters

image2D-array: Input image to be shifted.
shift1D-array: X- and y-shift to be applied.
padbool, optional: Pad the image before shifting it? Otherwise, it will wrap around the edges. The default is True.
pad_amountint, optional: Extra padding to be applied to the image. The default is 5.
nan_reflectedbool, optional: If True, the pixels that are reflected in the padding will be set to NaN after shifting.
crop_after_padbool, optional: Crop the image after padding it? The default is False.
cvalfloat, optional: Fill value for the padded pixels. The default is 0.
method‘fourier’ or ‘spline’ (not recommended), optional: Method for shifting the frames. The default is ‘fourier’.
kwargsdict, optional: Keyword arguments for the scipy.ndimage.shift routine. The default is {}.

Returns

imsft2D-array: The shifted image.

spaceKLIP.utils.interpret_dq_value(dq_value)[source]

Interpret DQ value using DQ definition

Parameters

dq_valueint: DQ value to interpret.

Returns

str: Interpretation of DQ value.

spaceKLIP.utils.load_pce_data()[source]

Load the consolidated PCE data from all_pces.npz.

Returns the data as a dict-like NpzFile object, cached at module level so it is only loaded once.

Returns

datadict-like: The loaded NpzFile object containing all PCE arrays and metadata.

spaceKLIP.utils.pop_pxar_kw(filepaths)[source]

Populate the PIXAR_A2 SCI header keyword which is required by pyKLIP in case it is not already available.

Parameters

filepathslist or array: File paths of the FITS files whose headers shall be checked.

spaceKLIP.utils.read_msk(maskfile)[source]

Read a PSF mask from a FITS file.

Parameters

maskfilepath: Path of input FITS file.

Returns

mask2D-array: PSF mask. None if not available.

spaceKLIP.utils.read_obs(fitsfile, return_var=False)[source]

Read an observation from a FITS file.

Parameters

fitsfilepath: Path of input FITS file.
return_varbool, optional: Return VAR_POISSON and VAR_RNOISE arrays? The default is False.

Returns

data3D-array: ‘SCI’ extension data.
erro3D-array: ‘ERR’ extension data.
pxdq3D-array: ‘DQ’ extension data.
head_priFITS header: Primary FITS header.
head_sciFITS header: ‘SCI’ extension FITS header.
is2dbool: Is the original data 2D?
align_shift2D-array: Array of shape (nints, 2) containing the alignment shifts applied to the frames. None if not available.
center_shift2D-array: Array of shape (nints, 2) containing the recentering shifts applied to the frames. None if not available.
align_mask2D-array: Array of shape (nints, 2) containing the alignment shifts applied to the masks. None if not available.
center_mask2D-array: Array of shape (nints, 2) containing the recentering shifts applied to the masks. None if not available.
maskoffs2D-array: Array of shape (nints, 2) containing the offsets between the star and coronagraphic mask position. None if not available.
var_poisson3D-array, optional: ‘VAR_POISSON’ extension data.
var_rnoise3D-array, optional: ‘VAR_RNOISE’ extension data.

spaceKLIP.utils.read_red(fitsfile)[source]

Read a reduction from a FITS file.

Parameters

fitsfilepath: Path of input FITS file.

Returns

data3D-array: ‘SCI’ extension data.
head_priFITS header: Primary FITS header.
head_sciFITS header: ‘SCI’ extension FITS header.
is2dbool: Is the original data 2D?

spaceKLIP.utils.recenterlsq(shift, image, method='fourier', kwargs={})[source]

Center a PSF on its nearest pixel by maximizing its peak count.

Parameters

shift1D-array: X- and y-shift to be applied.
image2D-array: Input image to be recentered.
method‘fourier’ or ‘spline’ (not recommended), optional: Method for shifting the frames. The default is ‘fourier’.
kwargsdict, optional: Keyword arguments for the scipy.ndimage.shift routine. The default is {}.

Returns

invpeakfloat: Inverse of the PSF’s peak count.

spaceKLIP.utils.set_surrounded_pixels(array, user_value=nan)[source]

Identifies pixels in a 2D array surrounded by NaN values on all eight sides and sets them to a user-defined value.

Parameters

arraynumpy.ndarray: 2D array containing numeric values and NaNs.
user_valuefloat or any valid value type, optional: Value to set for pixels surrounded by NaNs on all eight sides. Defaults to NaN.

Returns

numpy.ndarray: The input array with pixels surrounded by NaNs on all eight sides set to the user-defined value.

spaceKLIP.utils.subtractlsq(shift, image, ref_image, mask=None)[source]

Scale and subtract a reference from a science image.

Parameters

shift1D-array: Scaling factor between the science and the reference PSF.
image2D-array: Input image to be reference PSF-subtracted.
ref_image2D-array: Reference image.
mask2D-array, optional: Mask to be applied to the input and reference images. The default is None.

Returns

imres1D-array: Residual image collapsed into one dimension.

spaceKLIP.utils.write_fitpsf_images(fitpsf, fitsfile, row)[source]

Write a best fit FM PSF to a FITS file.

Parameters

fitpsfpyklip.fitpsf: PyKLIP PSF fitting object whose best fit FM PSF shall be saved.
fitsfilepath: Path of output FITS file.
rowastropy.table.Row: Astropy table row of the companion to be saved to the FITS file.

Returns

None.

spaceKLIP.utils.write_msk(maskfile, mask, fitsfile, mask_ext='_psfmask.fits')[source]

Write a PSF mask to a FITS file.

Parameters

maskfilepath: Path of input FITS file.
mask2D-array: PSF mask. None if not available.
fitsfilepath: Path of output FITS file (to save the PSF mask in the same directory).
mask_ext: str: Extension to append to the input fitsfile name to create the output maskfile name. Default is ‘_psfmask.fits’.

Returns

maskfilepath: Path of output FITS file.

spaceKLIP.utils.write_obs(fitsfile, output_dir, data, erro, pxdq, head_pri, head_sci, is2d, align_shift=None, center_shift=None, align_mask=None, center_mask=None, maskoffs=None, var_poisson=None, var_rnoise=None)[source]

Write an observation to a FITS file.

Parameters

fitsfilepath: Path of input FITS file.
output_dirpath: Directory where the output FITS file shall be saved.
data3D-array: ‘SCI’ extension data.
erro3D-array: ‘ERR’ extension data.
pxdq3D-array: ‘DQ’ extension data.
head_priFITS header: Primary FITS header.
head_sciFITS header: ‘SCI’ extension FITS header.
is2dbool: Is the original data 2D?
align_shift2D-array: Array of shape (nints, 2) containing the alignment shifts applied to the frames. None if not available.
center_shift2D-array: Array of shape (nints, 2) containing the recentering shifts applied to the frames. None if not available.
align_mask2D-array: Array of shape (nints, 2) containing the alignment shifts applied to the masks. None if not available.
center_mask2D-array: Array of shape (nints, 2) containing the recentering shifts applied to the masks. None if not available.
maskoffs2D-array, optional: Array of shape (nints, 2) containing the offsets between the star and coronagraphic mask position. The default is None.
var_poisson3D-array, optional: ‘VAR_POISSON’ extension data. The default is None.
var_rnoise3D-array, optional: ‘VAR_RNOISE’ extension data. The default is None.

Returns

fitsfilepath: Path of output FITS file.

spaceKLIP.utils.write_starfile(starfile, new_starfile_path, new_header=None)[source]

Save stellar spectrum file to a different location, and insert a header to the start if needed.

Parameters

starfilestr: Path to original stellar spectrum file.
new_starfile_pathstr: Path to new stellar spectrum file.
new_headerstr: Header to be inserted.

Returns

None

spaceKLIP.wcs_utils module

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

spaceKLIP.wcs_utils.draw_compass_mpl(image, orig_shape=None, wcs=None, show=True, zoom_limits=None, **kwargs)[source]

Visualize the compass using Matplotlib.

Parameters

imagendarray: 2D Numpy array (can be resampled).
orig_shapetuple of int or None: The original (non-resampled) array shape in (ny, nx), if different.
wcsobj or None: Associated original image WCS that is compatible with APE 14. If None given, compass is not drawn.
showbool: Display the plot.
zoom_limitsndarray or None: If not None, also draw a rectangle to represent the current zoom limits in the form of list of (x, y) representing the four corners of the zoom box.
kwargsdict: Keywords for matplotlib.pyplot.imshow.

Returns

image_base64str: Decoded buffer for Compass plugin.

spaceKLIP.wcs_utils.get_compass_info(image_wcs, image_shape, r_fac=0.4)[source]

Calculate WCS compass parameters. North (N) is up and East (E) is left.

Parameters

image_wcsobj: WCS that is compatible with APE 14.
image_shapetuple of int: Shape of the image in the form of (ny, nx).
r_facfloat: Scale factor for compass arrow length.

Returns

x, yfloat: Pixel positions for the center of the compass.
xn, ynfloat: Pixel positions for N of the compass.
xe, yefloat: Pixel positions for E of the compass.
degn, degefloat: Rotation angles for N and E, in degrees, for the compass, respectively.
xflipbool: Should display flip on X?