Detailed spaceKLIP API

spaceKLIP.analysistools module

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

Bases: object

The spaceKLIP astrophysical analysis tools class.

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

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

Parameters

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

Returns

None.

extract_companions(companions, starfile, mstar_err, spectral_type='G2V', klmode='max', date='auto', use_fm_psf=True, highpass=False, fitmethod='mcmc', fitkernel='diag', subtract=True, inject=False, overwrite=True, subdir='companions')[source]

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

Parameters

companionslist of list of three float, optional: List of companions to be extracted. For each companion, there should be a three element list containing guesses for [RA offset (arcsec), Dec offset (arcsec), contrast].
starfilepath: Path of VizieR VOTable containing host star photometry or two column TXT file with wavelength (micron) and flux (Jy).
mstar_errfloat or dict of float: Error on the host star magnitude. If float, will use the same value for each filter. If dict of float, the dictionary keys must be the JWST filters in use and a different value can be used for each filter.
spectral_typestr, optional: Host star spectral type for the stellar model SED. The default is ‘G2V’.
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.
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’.
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.
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’.

Returns

None.

raw_contrast(starfile, spectral_type='G2V', companions=None, overwrite_crpix=None, subdir='rawcon', output_filetype='npy', plot_xlim=(0, 10))[source]

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

Parameters

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

Returns

None.

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

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

Parameters

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

Returns

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

spaceKLIP.classpsfsubpipeline module

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

Run classical PSF subtraction on the input observations database.

Parameters

databasespaceKLIP.Database

SpaceKLIP database on which classical PSF subtraction shall be run.

kwargsdict, optional

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

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

The default is {}.

subdirstr, optional

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

Returns

None.

spaceKLIP.coron1pipeline module

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

Bases: Detector1Pipeline

The spaceKLIP JWST stage 1 pipeline class.

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

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

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

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

Parameters

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

Keyword Args

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

class_alias = 'calwebb_coron1'

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

Do a pseudo reference pixel correction

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

Parameters

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

Returns

resjwst.datamodel: Output JWST datamodel.

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

Do the default or a custom pseudo reference pixel correction.

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

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

Parameters

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

Returns

resjwst.datamodel: Output JWST datamodel.

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

Do the default or a custom saturation correction.

Parameters

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

Returns

resjwst.datamodel: Output JWST datamodel.

process(input)[source]

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

Parameters

inputjwst.datamodel: Input JWST datamodel to be processed.

Returns

outputjwst.datamodel: Output JWST datamodel.

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

Run a JWST pipeline step.

Parameters

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

Returns

resjwst.datamodel: Output JWST datamodel.

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

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

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

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

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

Parameters

databasespaceKLIP.Database

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

stepsdict, optional

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

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

Additional useful step parameters:

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

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

subdirstr, optional

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

overwritebool, optional

Overwrite existing files? Default is True.

quietbool, optional

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

verbosebool, optional

Print all info messages? Default is False.

Keyword Args

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

Returns

None.

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

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

WARNING: Will overwrite exiting files.

This customized implementation can:

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

Parameters

fitspathstr

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

output_dirstr

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

stepsdict, optional

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

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

Additional useful step parameters:

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

The default is {}.

Keyword Args

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

Returns

Pipeline output, either rate or rateint data model.

spaceKLIP.coron2pipeline module

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

Bases: Image2Pipeline

The spaceKLIP JWST stage 2 pipeline class.

class_alias = 'calwebb_coron2'

process(input)[source]

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

Parameters

inputjwst.datamodel: Input JWST datamodel to be processed.

Returns

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

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

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

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

Parameters

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

Keyword Args

save_resultsbool, optional: Save the JWST pipeline products? The default is True.
skip_bgbool, optional: Skip the background subtraction step? The default is False.
skip_photombool, optional: Skip the photometric correction step? The default is False.
skip_resamplebool, optional: Skip the resampling (drizzle) step? While the default is set to False, this step only applies to normal imaging modes and 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)[source]

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

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

Parameters

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

Keyword Args

save_resultsbool, optional: Save the JWST pipeline products? The default is True.
skip_bgbool, optional: Skip the background subtraction step? The default is False.
skip_photombool, optional: Skip the photometric correction step? The default is False.
skip_resamplebool, optional: Skip the resampling (drizzle) step? While the default is set to False, this step only applies to normal imaging modes and 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)[source]

Bases: Coron3Pipeline

The spaceKLIP JWST stage 3 pipeline class.

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

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

Parameters

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

Returns

asnpathpath: Path of the association file.

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

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

Parameters

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

Returns

None.

spaceKLIP.database module

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

Bases: object

The central spaceKLIP database class.

print_obs(include_fitsfiles=False)[source]

Print an abbreviated version of the observations database.

Parameters

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

Returns

None.

print_red(include_fitsfiles=False)[source]

Print an abbreviated version of the reductions database.

Parameters

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

Returns

None.

print_src(include_fitsfiles=False)[source]

Print an abbreviated version of the source database.

Parameters

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

Returns

None.

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

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

Parameters

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

Returns

None.

read_jwst_s3_data(datapaths)[source]

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

Parameters

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

Returns

None.

read_jwst_s4_data(datapaths)[source]

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

Parameters

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

Returns

None.

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

Returns

None.

update_obs(key, index, fitsfile, maskfile=None, nints=None, effinttm=None, xoffset=None, yoffset=None, crpix1=None, crpix2=None, blurfwhm=None)[source]

Update the content of the observations database.

Parameters

keystr: Database key of the observation to be updated.
indexint: Database index of the observation to be updated.
fitsfilepath: New FITS file path for the observation to be updated.
maskfilepath, optional: New PSF mask path for the observation to be updated. The default is None.
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 PSF x-position (pix, 1-indexed) for the observation to be updated. The default is None.
crpix2float, optional: New PSF y-position (pix, 1-indexed) for the observation to be updated. The default is None.
blurfwhmfloat, optional: New FWHM for the Gaussian filter blurring (pix) for the observation to be updated. The default is None.

Returns

None.

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

Update the content of the source database.

Parameters

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

Returns

None.

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

Create a spaceKLIP database from JWST data

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

Parameters

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

Keyword Arguments

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

spaceKLIP.imagetools module

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

Bases: object

The spaceKLIP image manipulation tools class.

align_frames(method='fourier', align_algo='leastsq', kwargs={}, subdir='aligned')[source]

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

Parameters

method‘fourier’ or ‘spline’ (not recommended), optional: Method for shifting the frames. The default is ‘fourier’.
align_algo‘leastsq’ or ‘header’: Algorithm to determine the alignment offsets. Default is ‘leastsq’, ‘header’ assumes perfect header offsets.
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’.

Returns

None.

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

Blur frames with a Gaussian filter.

Parameters

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

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

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')[source]

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_bpclean(data, erro, pxdq, NON_SCIENCE, bpclean_kwargs={})[source]

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

Parameters

data3D-array

Input images.

erro3D-array

Input image uncertainties.

pxdq3D-array

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

NON_SCIENCE3D-array

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

bpclean_kwargsdict, optional

Keyword arguments for the ‘bpclean’ 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 {}.

Returns

None.

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

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

Parameters

data3D-array: Input images.
erro3D-array: Input image uncertainties.
pxdq3D-array: Input binary bad pixel maps (1 = bad, 0 = good). Will be updated by the routine to include the newly flagged bad pixels.
keystr: Database key of the observation to be updated.
custom_kwargsdict, optional: Keyword arguments for the ‘custom’ method. The 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_nircam_centers(data0, key, j, spectral_type='G2V', date=None, output_dir=None, fov_pix=65, oversample=2, use_coeff=False)[source]

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

Parameters

data02D-array: Frame for which the star position shall be determined.
keystr: Database key of the observation containing the data0 frame.
jint: Database index of the observation containing the data0 frame.
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’.
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.

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+dqmed+medfilt', bpclean_kwargs={}, custom_kwargs={}, timemed_kwargs={}, dqmed_kwargs={}, medfilt_kwargs={}, types=['SCI', 'SCI_TA', 'SCI_BG', 'REF', 'REF_TA', 'REF_BG'], subdir='bpcleaned', restrict_to=None)[source]

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:

bpclean: 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.
dqmed: 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+dqmed+medfilt’.

bpclean_kwargsdict, optional

Keyword arguments for the ‘bpclean’ 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 {}.

dqmed_kwargsdict, optional

Keyword arguments for the ‘dqmed’ 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_dqmed(data, erro, pxdq, dqmed_kwargs={})[source]

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

Parameters

data3D-array

Input images.

erro3D-array

Input image uncertainties.

pxdq3D-array

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

dqmed_kwargsdict, optional

Keyword arguments for the ‘dqmed’ 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={})[source]

Replace bad pixels with an image plane median filter.

Parameters

data3D-array

Input images.

erro3D-array

Input image uncertainties.

pxdq3D-array

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

medfilt_kwargsdict, optional

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

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

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’.
methodstr: ‘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, or ‘simple’ for a simple np.nanmedian
sigmafloat: number of standard deviations to use for the clipping limit in sigma_clipped_stats, if the robust option is selected.
borderwidthint: 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, but writes out new files to subdir and updates database.

update_nircam_centers()[source]: Determine offset between SIAF reference pixel position and true mask center from Jarron and update the current reference pixel position to reflect the true mask center. Account for filter-dependent distortion. Might not be required for simulated data.

Returns

None.

spaceKLIP.mast module

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

Retrieve data products from MAST

Parameters

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

Other kwargs are passed to get_mast_filename

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

Download any specified filename from MAST, writing to outputdir

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

Set progress=True to show a progress bar.

verbose toggles on/off minor informative text output

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

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

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

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

Parameters

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

Returns

None.

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

spaceKLIP.plotting module

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

Plot a compass annotation onto an image, to indicate 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: axis to draw into
imagendarray: 2D image to be annotated (used just to get the image dimensions)
wcsastropy.wcs.WCS: World Coordinate System information
xf, yffloats: X and Y fractions of the image, to specify the location where the compass should be displayed. Values should be between 0 and 1.
length_fractionfloat: Length of the compass, as a fraction of the size of the entire image
colorstr: Color
fontsizefloat: Font size

Returns

None.

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

Plot a scale bar on an image.

Parameters

axmatplotlib.Axes: axis to draw into
imagendarray: 2D image to be annotated (used just to get the image dimensions)
wcsastropy.wcs.WCS: World Coordinate System information
lengthastropy.Quantity: Length of the scale bar, in arcsec or equivalent unit
xf, yffloats: X and Y fractions of the image, to specify the location where the compass should be displayed. Values should be between 0 and 1.
colorstr: Color
fontsizefloat: Font size
lwfloat: line width

Returns

None.

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

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

Parameters

axmatplotlib.Axes: axis to draw into
imagendarray: 2D image to be annotated (used just to get the image dimensions)
wcsastropy.wcs.WCS: World Coordinate System information

Returns

None.

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

spaceKLIP.plotting.display_coron_dataset(database, restrict_to=None, save_filename=None, stage3=None)[source]

Display multiple files in a coronagraphic dataset.

# TODO potentially provide other ways of filtering the data, e.g. to show only the PSF stars or only references, etc.

Parameters

databasespaceklip.Database: database of files to plot
restrict_tostr, optional: Optional query string to only display some data. 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.
save_filenamestr: If provided, the plots will be saved to a PDF file with this name.

Returns

None.

spaceKLIP.plotting.display_coron_image(filename)[source]

Display and annotate a coronagraphic image.

Shows image on asinh scale along with some basic metadata, scale bar, and compass.

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: Filename

Returns

None.

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

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)[source]: Plot MCMC chains from companion fitting

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

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

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

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

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

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

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

Parameters

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

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

spaceKLIP.psf module

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

Bases: object

Create coronagraphic PSFs for JWST NIRCam and MIRI

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

There are multiple ways to estimate these PSFs:

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

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

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

property bandpass

property filter

property fov_pix

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

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

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

Parameters

locfloat or ndarray

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

PA_V3float

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

return_oversamplebool

Return the oversampled version of the PSF?

do_shiftbool

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

addV3Yidlbool

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

normalizestr

How to normalize the PSF. Options are:

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

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.
sppysynphot spectrum: Manually specify spectrum to get a desired wavelength weighting. Only applicable if quick=False. If not set, defaults to self.sp.

Returns

None.

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

Generate offset PSF in detector frame.

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

Parameters

coord_valstuple or None

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

coord_framestr

Type of input coordinates. Default is ‘idl’.

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

quickbool

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

sppysynphot 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

Returns

None.

property image_mask

property name

property oversample

property pupil_mask

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

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

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

Parameters

rfloat or ndarray

Radial offst from mask center.

thfloat or ndarray

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

PA_V3float

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

frame_outstr

Coordinate frame of output. Default is ‘idl’.

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

Returns

None.

property use_coeff

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

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

Parameters

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

Returns

offsetpsf2D-array: WebbPSF model PSF.

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

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

Parameters

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

Returns

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

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

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

Parameters

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

Returns

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

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

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

Parameters

image2D-array: Input image to be recentered.

Returns

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

spaceKLIP.pyklippipeline module

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

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

Parameters

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

Returns

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

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

Run pyKLIP on the input observations database.

Parameters

databasespaceKLIP.Database

SpaceKLIP database on which pyKLIP shall be run.

kwargsdict, optional

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

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

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)[source]

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)[source]

Read a spectrum from a TXT file.

Parameters

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

Returns

sedsynphot.SourceSpectrum: Spectrum of the source.

spaceKLIP.utils module

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

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

Parameters

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

Returns

imres1D-array: Residual image collapsed into one dimension.

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

Calculate reduced chi square metric

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

Parameters

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

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

Crop an image.

Parameters

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

Returns

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

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

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

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

Parameters

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

Keyword Args

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

Returns

Mask of bad pixels with same shape as input cube.

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

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)[source]

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

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 webbpsf without first check web server.
return_morebool: If True, also return do_svo variable, whether SVO was used or not.

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

Get mask name from aperture name

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

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

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

Parameters

apnamestr: String aperture name as described above

Returns

image_maskstr: String for image mask

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

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

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

Parameters

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

Returns

tp_comsubstfloat: COM substrate transmission averaged over the respective filter profile

spaceKLIP.utils.imshift(image, shift, pad=False, cval=0.0, method='fourier', kwargs={})[source]

Shift an image.

Parameters

image2D-array: Input image to be shifted.
shift1D-array: X- and y-shift to be applied.
padbool, optional: Pad the image before shifting it? Otherwise, it will wrap around the edges. The default is True.
cvalfloat, optional: Fill value for the padded pixels. The default is 0.
method‘fourier’ or ‘spline’ (not recommended), optional: Method for shifting the frames. The default is ‘fourier’.
kwargsdict, optional: Keyword arguments for the scipy.ndimage.shift routine. The default is {}.

Returns

imsft2D-array: The shifted image.

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

Interpret DQ value using DQ definition

Parameters

dq_valueint: DQ value to interpret.

Returns

str: Interpretation of DQ value.

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

Read a PSF mask from a FITS file.

Parameters

maskfilepath: Path of input FITS file.

Returns

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

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

Read an observation from a FITS file.

Parameters

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

Returns

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

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

Read a reduction from a FITS file.

Parameters

fitsfilepath: Path of input FITS file.

Returns

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

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

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

Parameters

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

Returns

invpeakfloat: Inverse of the PSF’s peak count.

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

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

Parameters

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

Returns

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

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

Scale and subtract a reference from a science image.

Parameters

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

Returns

imres1D-array: Residual image collapsed into one dimension.

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

Write a best fit FM PSF to a FITS file.

Parameters

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

Returns

None.

spaceKLIP.utils.write_msk(maskfile, mask, fitsfile)[source]

Write a PSF mask to a FITS file.

Parameters

maskfilepath: Path of input FITS file.
mask2D-array: PSF mask. None if not available.
fitsfilepath: Path of output FITS file (to save the PSF mask in the same directory).

Returns

maskfilepath: Path of output FITS file.

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

Write an observation to a FITS file.

Parameters

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

Returns

fitsfilepath: Path of output FITS file.

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

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