Detailed spaceKLIP API

spaceKLIP.analysistools module

class spaceKLIP.analysistools.AnalysisTools(database)

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), **kwargs)

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, **kwargs)

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. 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?

Returns

None.

raw_contrast(starfile, spectral_type='G2V', companions=None, overwrite_crpix=None, subdir='rawcon', output_filetype='npy', plot_xlim=(0, 10), save_figures=True, **kwargs)

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)

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')

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)

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)

Loss function for the minimization process in fit_for_extended_sources.

spaceKLIP.classpsfsubpipeline module

spaceKLIP.classpsfsubpipeline.run_obs(database, kwargs={}, subdir='psfsub')

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)

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)

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)

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)

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)

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)

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)

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.

**kwargskeyword arguments

Default JWST pipeline step keyword arguments.

Returns

resjwst.datamodel

Output JWST datamodel.

setup_output(input)

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)

Bases: JwstStep

Mask particular groups prior to ramp fitting

class_alias = 'maskgroups'

process(input)

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.prepare_group_masking_advanced(steps, observations, refpath, reftype, quiet=False)

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)

spaceKLIP.coron1pipeline.prepare_group_masking_custom(steps, observations, quiet=False)

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

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)

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)

Bases: Image2Pipeline

The spaceKLIP JWST stage 2 pipeline class.

class_alias = 'calwebb_coron2'

process(input)

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)

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 skips coronagraphic observation. 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)

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 skips coronagraphic observation. 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)

Bases: Coron3Pipeline

The spaceKLIP JWST stage 3 pipeline class.

spaceKLIP.coron3pipeline.make_asn_file(database, key, output_dir)

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')

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)

Bases: object

The central spaceKLIP database class.

adjust_dir(dir_path, data_type)

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)

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)

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)

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)

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)

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)

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()

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, nints=None, effinttm=None, xoffset=None, yoffset=None, crpix1=None, crpix2=None, maskcenx=None, maskceny=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)

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.

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.

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)

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, obsids=None, input_dir=None, psflibpaths=None, bgpaths=None, assoc_using_targname=True, verbose=True, readlevel='012', cr_from_siaf=False, **kwargs)

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)

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)

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

Parameters

1. countrates [array of count rates at which the bias is desired]

2. sig [float, single read noise]

3. 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

1. 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)

Bases: JwstStep

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

class_alias = 'experimental_jumpramp'

create_alldiffs2use(datamodel, shape)

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)

Create the covariance matrix

Parameters

datamodelJWST datamodel

JWST ramp datamodel

Returns

CCovar() object

Covariance matrix object

create_diffs(datamodel, C)

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)

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)

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)

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)

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)

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)

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)

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

Bases: object

fill_masked_reads(diffs2use)

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

1. 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)

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

1. diffs [resultant differences, shape (ndiffs, npix)]

2. Cov [class Covar, holds the covariance matrix information]

3. 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.]

5. diffs2use [shape (ndiffs, npix), boolean mask of whether to use

   each resultant difference for each pixel. Default None]

6. detect_jumps [run the jump detection machinery leaving out

   single and consecutive resultant differences. Default False]

7. resetval [float or array of shape (npix): priors on the reset

   values. Default 0. Irrelevant unless Cov.pedestal is True.]

8. 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.]

9. 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)

Function getramps: make some synthetic ramps

Parameters

1. countrate [electrons/time]

2. sig [single read read noise, electrons]

3. 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

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

spaceKLIP.expjumpramp.jumpramp_column(i, int_diffs, C, sig, int_diffs2use)

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)

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)

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

Parameters

1. diffs [resultant differences]

2. Cov [class Covar, holds the covariance matrix information. Must

   be based on differences alone (i.e. without the pedestal)]

3. 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]

5. threshold_twoomit [float, minimum chisq improvement to exclude

   two sequential resultant differences. Default 23.8, i.e., 4.5 sigma]

6. 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

1. 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.]

2. 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)

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()

Create an average channel image representing the common 1/f noise

clean(model_type='savgol', vertical_corr=False, **kwargs)

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)

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)

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)

Use photutils Background2D to remove spatially varying background

clean(model_type='savgol', vertical_corr=False, **kwargs)

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)

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)

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)

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)

Apply 1/f noise correction to a JWST ImageModel

proc_RampModel(input)

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)

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)

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 horizontal 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)

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)

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)

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)

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)

Bases: JwstStep

kTCSubtractStep: Subtract kTC noise from ramp data.

class_alias = 'removektc'

process(input)

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)

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()

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)

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)

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)

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')

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)

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')

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.

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

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.

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 {}.

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.

coadd_frames(nframes=None, types=['SCI', 'SCI_BG', 'REF', 'REF_BG'], subdir='coadded')

Coadd frames.

Parameters

nframesint, optional

Number of frames to be coadded. Modulo frames will be removed. If None, will coadd all frames in an observation. The default is None.

typeslist of str, optional

List of data types from which the frames shall be coadded. 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 ‘coadded’.

Returns

None.

crop_frames(npix=1, types=['SCI', 'SCI_BG', 'REF', 'REF_BG'], subdir='cropped')

Crop all frames.

Parameters

npixint or list of four int, optional

Number of pixels to be cropped from the frames. If int, the same number of pixels will be cropped on each side. If list of four int, a different number of pixels can be cropped from the [left, right, bottom, top] of the frames. The default is 1.

typeslist of str, optional

List of data types from which the frames shall be cropped. 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 ‘cropped’.

Returns

None.

find_bad_pixels(method='dqarr', set_dq_zero=True, dqarr_kwargs={}, sigclip_kwargs={}, custom_kwargs={}, timeints_kwargs={}, gradient_kwargs={}, types=['SCI', 'SCI_TA', 'SCI_BG', 'REF', 'REF_TA', 'REF_BG'], subdir='bpfound', restrict_to=None)

Identify bad pixels for cleaning

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:

• dqarr: uses DQ array to identify bad pixels

• sigclip: use sigma clipping to identify additional bad pixels.

• custom: use 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:

The default is {}.

sigclip_kwargsdict, optional

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

• sigma: float, 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 {}.

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’.

Returns

None

find_bad_pixels_custom(data, erro, pxdq, key, custom_kwargs={})

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 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 {}.

Returns

None.

find_bad_pixels_gradient(data, erro, pxdq, key, gradient_kwargs={})

find_bad_pixels_sigclip(data, erro, pxdq, NON_SCIENCE, sigclip_kwargs={})

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].

The default is {}.

Returns

None.

find_bad_pixels_timeints(data, erro, pxdq, NON_SCIENCE, timeints_kwargs={})

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.

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)

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)

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_interp2d(data, erro, pxdq, interp2d_kwargs={})

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 4.

The default is {}.

Returns

None.

fix_bad_pixels_localmed(data, erro, pxdq, localmed_kwargs={})

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={})

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.

The default is {}.

Returns

None.

fix_bad_pixels_timemed(data, erro, pxdq, timemed_kwargs={})

Replace pixels which are only bad in some frames with their median value from the good frames.

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.

timemed_kwargsdict, optional

Keyword arguments for the ‘timemed’ method. Available keywords are: - n/a The default is {}.

Returns

None.

hpf(size='auto', types=['SCI', 'SCI_BG', 'REF', 'REF_BG'], subdir='filtered')

Blur frames with a Gaussian filter.

Parameters

size‘auto’ 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 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.

inject_companions(companions, starfile, spectral_type, output_dir, highpass=False, subdir='test', date='auto', kwargs={})

Function to inject synthetic PSFs into a set of frames loaded from a dataset, and save the new frames with the injected companion.

Parameters

companionslist of list of three float, optional

List of companions to be injected. For each companion, there should be a three element list containing [RA offset (arcsec), Dec offset (arcsec), contrast].

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.

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

None

pad_frames(npix=1, cval=nan, types=['SCI', 'SCI_BG', 'REF', 'REF_BG'], subdir='padded')

Pad all frames.

Parameters

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.

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.

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

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')

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')

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')

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')

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')

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')

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')

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)

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_miri_offsets()

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)

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)

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.suppress_stdout()

Context manager to suppress stdout

spaceKLIP.mast module

spaceKLIP.mast.download_files(product_table, outputdir='.', verbose=True, **kwargs)

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)

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)

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)

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)

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)

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)

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)

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')

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)

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)

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='spaceKLIP.sk_style')

Load the matplotlib style for spaceKLIP plots.

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

spaceKLIP.plotting.plot_chains(chain, savefile)

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 calibrated throughput alongside calibrated contrast curves.

spaceKLIP.plotting.plot_contrast_images(meta, data, data_masked, pxsc=None, savefile='./maskimage.pdf')

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 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 forward model psf

spaceKLIP.plotting.plot_injected_locs(meta, data, transmission, seps, pas, pxsc=None, savefile='./injected.pdf')

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)

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.tickFont(ax, xy, fontproperties)

spaceKLIP.psf module

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

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)

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')

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)

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)

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)

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)

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)

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)

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

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)

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')

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)

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)

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)

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)

spaceKLIP.psflib.update_db_sptypes(refdb)

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)

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')

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.

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, return_si=False, output_dir=None, **kwargs)

Get the source brightness and zero point fluxes in each filter of the JWST instrument in use.

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’, ‘NIRISS’, or ‘MIRI’

JWST instrument in use.

return_sibool, optional

Return the filter zero point in SI units in addition to Jy? The default is False.

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_sidict, optional

Dictionary of the zero point flux (erg/cm^2/s/A) of each filter of the JWST instrument in use.

spaceKLIP.starphot.read_spec_file(starfile)

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.utils module

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

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)

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>)

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)

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)

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)

Fit unsaturated data and return coefficients

spaceKLIP.utils.cube_outlier_detection(data, sigma_cut=10, nint_min=10)

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)

spaceKLIP.utils.gaussian_kernel(sigma_x=1, sigma_y=1, theta_degrees=0, n=6)

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)

Get DQ mask from DQ array.

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

Parameters

dqarrndarray

DQ array. Either 2D or 3D.

bitvalueslist

List of bit values to use for DQ mask. These values must be powers of 2 (e.g., 1, 2, 4, 8, 16, …), representing the specific DQ bit flags.

spaceKLIP.utils.get_filter_info(instrument, timeout=1, do_svo=True, return_more=False)

Load filter information from the SVO Filter Profile Service or webbpsf

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)

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_siaf(inst)

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)

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)

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={})

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)

Interpret DQ value using DQ definition

Parameters

dq_valueint

DQ value to interpret.

Returns

str

Interpretation of DQ value.

spaceKLIP.utils.pop_pxar_kw(filepaths)

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)

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)

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)

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={})

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)

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)

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)

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)

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).

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)

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)

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

Copyright 2020-2023 JDADF Developers

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)

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)

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?