pynrc.NIRCam

class pynrc.NIRCam(filter='F210M', pupil=None, mask=None, module='A', ND_acq=False, apname=None, **kwargs)[source]

Bases: object

NIRCam base instrument class

Creates a NIRCam instrument class that holds all the information pertinent to an observation using a given channel/module (SWA, SWB, LWA, LWB).

The user merely inputs the filter name, pupil element, coronagraphic mask, and module A or B. Based on these settings, a sequence of detector objects will be created that spans the correct channel. For instance, a filter value of ‘F210M’ paired with module=’A’ will generate four detector objects, one for each of the four SWA SCAs 481-484 (A1-A4, if you prefer).

A number of other options are passed via the kwargs parameter that allow setting of the detector readout mode, MULTIACCUM settings, and settings for the PSF calculation to be passed to WebbPSF.

Parameters
  • filter (str) – Name of NIRCam filter.

  • pupil (str, None) – NIRCam pupil elements such as grisms or lyot stops (default: None).

  • mask (str, None) – Specify which coronagraphic occulter (default: None).

  • module (str) – NIRCam Module ‘A’ or ‘B’ (default: ‘A’).

  • ND_acq (bool) – ND square acquisition (default: False).

  • ice_scale (float) – Add in additional OTE H2O absorption. This is a scale factor relative to 0.0131 um thickness. No ice contributions by default.

  • nvr_scale (float) – Add in additional NIRCam non-volatile residue. This is a scale factor relative to 0.280 um thickness. If set to None, then assumes a scale factor of 1.0 as is contained in the NIRCam filter curves. Setting nvr_scale=0 will remove these contributions.

Notes

Detector Settings

The following keyword arguments will be passed to both the DetectorOps and multiaccum instances. These can be set directly upon initialization of the of the NIRCam instances or updated later using the update_detectors() method. All detector instances will be considered to operate in this mode.

Keyword Arguments
  • det_list (list, None) – List of detector names (481, 482, etc.) to consider. If not set, then defaults are chosen based on observing mode.

  • wind_mode (str) – Window mode type ‘FULL’, ‘STRIPE’, ‘WINDOW’.

  • xpix (int) – Size of window in x-pixels for frame time calculation.

  • ypix (int) – Size of window in y-pixels for frame time calculation.

  • x0 (int) – Lower-left x-coord position of detector window.

  • y0 (int) – Lower-left y-coord position of detector window.

  • read_mode (str) – NIRCam Ramp Readout mode such as ‘RAPID’, ‘BRIGHT1’, etc.

  • nint (int) – Number of integrations (ramps).

  • ngroup (int) – Number of groups in a integration.

  • nf (int) – Number of frames per group.

  • nd1 (int) – Number of drop frame after reset (before first group read).

  • nd2 (int) – Number of drop frames within a group (ie., groupgap).

  • nd3 (int) – Number of drop frames after final read frame in ramp.

Notes

PSF Settings

The following keyword arguments will be passed to the PSF generation function psf_coeff() which calls webbpsf. These can be set directly upon initialization of the of the NIRCam instances or updated later using the update_psf_coeff() method.

Keyword Arguments
  • fov_pix (int) – Size of the FoV in pixels (real SW or LW pixels). The defaults depend on the type of observation.

  • oversample (int) – Factor to oversample during WebbPSF calculations. Default 2 for coronagraphy and 4 otherwise.

  • offset_r (float) – Radial offset from the center in arcsec.

  • offset_theta (float) – Position angle for radial offset, in degrees CCW.

  • bar_offset (float or None) – For bar masks, the position along the bar to place the PSF (arcsec). Use offset_bar() for filter-dependent locations. If not set, default is to decide location based on selected filter. Updates bar_offset attribute.

  • wfe_drift (float) – Wavefront error drift amplitude in nm. Updates wfe_drift attribute.

  • opd (tuple or HDUList) – Tuple (file, slice) or filename or HDUList specifying OPD.

  • include_si_wfe (bool) – Include SI WFE measurements? Default=False.

  • tel_pupil (str) – File name or HDUList specifying telescope entrance pupil.

  • jitter (str or None) – Currently either ‘gaussian’ or None.

  • jitter_sigma (float) – If jitter = 'gaussian', then this is the size of the blurring effect.

  • save (bool) – Save the resulting PSF coefficients to a file? (default: True)

  • force (bool) – Forces a recalcuation of PSF even if saved PSF exists. (default: False)

  • quick (bool) – Only perform a fit over the filter bandpass with a smaller default polynomial degree fit. Not compatible with save.

Examples

Basic example of generating a full frame NIRCam observation:

>>> inst = pynrc.NIRCam('F210M', module='A', read_mode='DEEP8', nint=10, ngroup=5)

is the same as:

>>> inst = pynrc.NIRCam('F210M', module='A')
>>> inst.update_detectors(read_mode='DEEP8', nint=10, ngroup=5)

Attributes Summary

ND_acq

Use Coronagraphic ND acquisition square?

bandpass

The wavelength dependent bandpass.

bar_offset

Offset position along bar mask (arcsec).

channel

NIRCam wavelength channel (‘SW’ or ‘LW’).

det_info

Dictionary housing detector info parameters and keywords.

filter

Name of filter bandpass

filter_list

List of allowable filters.

mask

Name of coronagraphic mask element

mask_list

List of allowable coronagraphic mask values.

module

NIRCam modules A or B

multiaccum

multiaccum object

multiaccum_times

Exposure timings in dictionary

pixelscale

Pixel scale in arcsec/pixel

psf_coeff

Cube of polynomial coefficients used to generate a PSF.

psf_coeff_bg

Cube of polynomial coefficients used to generate a PSF.

psf_info

Info used to create psf_coeff.

psf_info_bg

Info used to create psf_coeff for faint background sources.

pupil

Name of pupil element

pupil_list

List of allowable pupil mask values.

well_level

Detector well level in units of electrons

wfe_drift

WFE drift relative to nominal PSF (nm)

Methods Summary

bg_zodi([zfact])

Zodiacal background flux.

gen_exposures([sp, im_slope, file_out, …])

Generate raw mock data.

gen_psf([sp, return_oversample, use_bg_psf])

PSF image.

plot_bandpass([ax, color, title])

Plot the instrument bandpass on a selected axis.

ramp_optimize(sp[, sp_bright, is_extended, …])

Optimize ramp settings.

sat_limits([sp, bp_lim, units, well_frac, …])

Saturation limits.

saturation_levels(sp[, full_size, ngroup])

Saturation levels.

sensitivity([nsig, units, sp, verbose])

Sensitivity limits.

update_detectors([verbose, det_list])

Generates a list of detector objects depending on module and channel.

update_psf_coeff([fov_pix, oversample, …])

Create new PSF coefficients.

Methods Documentation

bg_zodi(zfact=None, **kwargs)[source]

Zodiacal background flux.

There are options to call jwst_backgrounds to obtain better predictions of the background. Specify keywords ra, dec, and thisday to use jwst_backgrounds.

Returned values are in units of e-/sec/pixel

Parameters

zfact (float) – Factor to scale Zodiacal spectrum (default 2.5)

Keyword Arguments
  • ra (float) – Right ascension in decimal degrees

  • dec (float) – Declination in decimal degrees

  • thisday (int) – Calendar day to use for background calculation. If not given, will use the average of visible calendar days.

Notes

Representative values for zfact:

  • 0.0 - No zodiacal emission

  • 1.0 - Minimum zodiacal emission from JWST-CALC-003894

  • 1.2 - Required NIRCam performance

  • 2.5 - Average (default)

  • 5.0 - High

  • 10.0 - Maximum

gen_exposures(sp=None, im_slope=None, file_out=None, return_results=None, targ_name=None, timeFileNames=False, DMS=True, det_name=None, dark=True, bias=True, det_noise=True, nproc=None, **kwargs)[source]

Generate raw mock data.

Create a series of ramp integration saved to FITS files based on the current NIRCam settings. This method calls the gen_fits() function, which in turn calls the detector noise generator ngNRC.

Only works on one detector at a time.

Currently, this image simulator does NOT take into account:

  • QE variations across a pixel’s surface

  • Intrapixel Capacitance (IPC)

  • Post-pixel Coupling (PPC) due to ADC “smearing”

  • Pixel non-linearity

  • Persistence/latent image

  • Optical distortions

  • Zodiacal background roll off for grism edges

  • Cosmic Rays

TODO: Double-check the output for grism data w.r.t sci_to_det().

Parameters
  • im_slope (numpy array, None) – Pass the slope image directly. If not set, then a slope image will be created from the input spectrum keyword. This should include zodiacal light emission, but not dark current. Make sure this array is in detector coordinates.

  • sp (pysynphot.spectrum, None) – A pysynphot spectral object. If not specified, then it is assumed that we’re looking at blank sky.

  • targ_name (str, None) – A target name for the exposure file’s header.

  • file_out (str, None) – Path and name of output FITs files. Time stamps will be automatically inserted for unique file names if timeFileNames=True.

  • timeFileNames (bool) – Save the exposure times in the file name? This is useful to see the timing, but also makes it a little harder to combine INTs later for DMS simulations.

  • DMS (bool) – Create DMS data file and header format? Otherwise, the output is more similar to ISIM CV2/3 and OTIS campaigns.

  • return_results (bool, None) – By default, we return results if file_out is not set and the results are not returned if file_out is set. This decision is based on the large amount of data and memory usage this method may incur if the results were always returned by default. Instead, it’s better to save the FITs to disk, especially if NINTs is large. We include the return_results keyword if the user would like to do both (or neither).

  • det_name (str, None) – Name of detector (A1-B5). If not found or set to None, then the first detector in self.det_list and self.Detectors is used.

  • dark (bool) – Include the dark current?

  • bias (bool) – Include the bias frame?

  • nproc (int) – Advanced usage to explicitly specify the number of processors to use. Otherwise, a function is called to determine the optimum number of processes based on available memory and number of ramps being generated.

  • det_noise (bool) – Include detector noise components? If set to False, then only perform Poisson noise. Darks and biases are also excluded.

Keyword Arguments
  • zfact (float) – Factor to scale Zodiacal spectrum (default 2.5)

  • ra (float) – Right ascension in decimal degrees

  • dec (float) – Declination in decimal degrees

  • thisday (int) – Calendar day to use for background calculation. If not given, will use the average of visible calendar days.

gen_psf(sp=None, return_oversample=False, use_bg_psf=False, **kwargs)[source]

PSF image.

Create a PSF image from instrument settings. The image is noiseless and doesn’t take into account any non-linearity or saturation effects, but is convolved with the instrument throughput. Pixel values are in counts/sec. The result is effectively an idealized slope image (no background).

If no spectral dispersers (grisms or DHS), then this returns a single image or list of images if sp is a list of spectra. By default, it returns only the detector-sampled PSF, but setting return_oversample=True will also return a set of oversampled images as a second output.

Parameters
  • sp (pysynphot.spectrum) – If not specified, the default is flat in phot lam (equal number of photons per spectral bin). The default is normalized to produce 1 count/sec within that bandpass, assuming the telescope collecting area and instrument bandpass. Coronagraphic PSFs will further decrease this due to the smaller pupil size and coronagraphic spot.

  • return_oversample (bool) – If True, then also returns the oversampled version of the PSF

  • use_bg_psf (bool) – If a coronagraphic observation, off-center PSF is different.

plot_bandpass(ax=None, color=None, title=None, **kwargs)[source]

Plot the instrument bandpass on a selected axis. Can pass various keywords to matplotlib.plot function.

Parameters
  • ax (matplotlib.axes, optional) – Axes on which to plot bandpass.

  • color – Color of bandpass curve.

  • title (str) – Update plot title.

Returns

matplotlib.axes – Updated axes

ramp_optimize(sp, sp_bright=None, is_extended=False, patterns=None, snr_goal=None, snr_frac=0.02, tacq_max=None, tacq_frac=0.1, well_frac_max=0.8, nint_min=1, nint_max=5000, ng_min=2, ng_max=None, return_full_table=False, even_nints=False, verbose=False, **kwargs)[source]

Optimize ramp settings.

Find the optimal ramp settings to observe a spectrum based on input constraints. This function quickly runs through each detector readout pattern and calculates the acquisition time and SNR for all possible settings of NINT and NGROUP that fulfill the SNR requirement (and other constraints).

The final output table is then filtered, removing those exposure settings that have the same exact acquisition times but worse SNR. Further “obvious” comparisons are done that exclude settings where there is another setting that has both better SNR and less acquisition time. The best results are then sorted by an efficiency metric (SNR / sqrt(acq_time)). To skip filtering of results, set return_full_table=True.

The result is an AstroPy Table.

Parameters
  • sp (pysynphot.spectrum) – A pysynphot spectral object to calculate SNR.

  • sp_bright (pysynphot.spectrum, None) – Same as sp, but optionally used to calculate the saturation limit (treated as brightest source in field). If a coronagraphic mask observation, then this source is assumed to be occulted and sp is fully unocculted.

  • is_extended (bool) – Treat sp source as extended object, then in units/arcsec^2

  • snr_goal (float) – Minimum required SNR for source. For grism, this is the average SNR for all wavelength.

  • snr_frac (float) – Give fractional buffer room rather than strict SNR cut-off.

  • tacq_max (float) – Maximum amount of acquisition time in seconds to consider.

  • tacq_frac (float) – Fractional amount of time to consider exceeding tacq_max.

  • patterns (numpy array) – Subset of MULTIACCUM patterns to check, otherwise check all.

  • nint_min/max (int) – Min/max number of desired integrations.

  • ng_min/max (int) – Min/max number of desired groups in a ramp.

  • well_frac_max (float) – Maximum level that the pixel well is allowed to be filled. Fractions greater than 1 imply hard saturation, but the reported SNR will not be aware of any saturation that may occur to sp.

  • even_nints (bool) – Return only the even NINTS

  • return_full_table (bool) – Don’t filter or sort the final results (ingores event_ints).

  • verbose (bool) – Prints out top 10 results.

Keyword Arguments
  • zfact (float) – Factor to scale Zodiacal spectrum (default 2.5)

  • ra (float) – Right ascension in decimal degrees

  • dec (float) – Declination in decimal degrees

  • thisday (int) – Calendar day to use for background calculation. If not given, will use the average of visible calendar days.

  • ideal_Poisson (bool) – Use total signal for noise estimate? Otherwise MULTIACCUM equation is used. Default = True

  • rad_EE (int) – Extraction aperture radius (in pixels) for imaging mode.

  • dw_bin (float) – Delta wavelength to calculate spectral sensitivities for grisms and DHS.

  • ap_spec (float, int) – Instead of dw_bin, specify the spectral extraction aperture in pixels. Takes priority over dw_bin. Value will get rounded up to nearest int.

Note

The keyword arguments ra, dec, thisday are not recommended for use given the amount of time it takes to query the web server. Instead, use bg_zodi() to match a zfact estimate.

Returns

astropy table – A sorted and filtered table of ramp options.

sat_limits(sp=None, bp_lim=None, units='vegamag', well_frac=0.8, ngroup=None, trim_psf=33, verbose=False, **kwargs)[source]

Saturation limits.

Generate the limiting magnitude (80% saturation) with the current instrument parameters (filter and ramp settings) assuming some spectrum. If no spectrum is defined, then a G2V star is assumed.

The user can also define a separate bandpass in which to determine the limiting magnitude that will cause the current NIRCam bandpass to saturate.

Parameters
  • sp (pysynphot.spectrum) – Spectrum to determine saturation limit.

  • bp_lim (pysynphot.obsbandpass) – Bandpass to report limiting magnitude.

  • units (str) – Output units (defaults to vegamag).

  • well_frac (float) – Fraction of full well to consider ‘saturated’.

  • ngroup (int, None) – Option to specify the number of groups to determine integration time. If not set, then the default is to use those specified in the Detectors class. Can set ngroup=0 for the so-called Zero Frame in the event there are multiple reads per group.

  • trim_psf (int, None) – Option to crop the PSF coefficient around the brightest pixel. For PSFs with large fov_pix values, this option helps speed up the saturation limit calculation. Afterall, we’re usually only interested in the brightest pixel when calculating saturation limits. Set to None to use the ‘fov_pix’ value. Default = 33 (detector pixels).

  • verbose (bool) – Print result details.

Example

>>> nrc = pynrc.NIRCam('F430M') # Initiate NIRCam observation
>>> sp_A0V = pynrc.stellar_spectrum('A0V') # Define stellar spectral type
>>> bp_k = S.ObsBandpass('steward,k') # Pysynphot K-Band bandpass
>>> bp_k.name = 'K-Band'
>>> mag_lim = nrc.sat_limits(sp_A0V, bp_k, verbose=True)

Returns K-Band Limiting Magnitude for F430M assuming A0V source.

saturation_levels(sp, full_size=True, ngroup=2, **kwargs)[source]

Saturation levels.

Create image showing level of saturation for each pixel. Can either show the saturation after one frame (default) or after the ramp has finished integrating (ramp_sat=True).

Parameters
  • sp (pysynphot.spectrum) – A pysynphot spectral object (normalized).

  • full_size (bool) – Expand (or contract) to size of detector array? If False, use fov_pix size.

  • ngroup (int) – How many group times to determine saturation level? If this number is higher than the total groups in ramp, then a warning is produced. The default is ngroup=2, A value of 0 corresponds to the so-called “zero-frame,” which is the very first frame that is read-out and saved separately. This is the equivalent to ngroup=1 for RAPID and BRIGHT1 observations.

sensitivity(nsig=10, units=None, sp=None, verbose=False, **kwargs)[source]

Sensitivity limits.

Convenience function for returning the point source (and surface brightness) sensitivity for the given instrument setup. See bg_sensitivity() for more details.

Parameters
  • sp (pysynphot.spectrum) – Input spectrum to use for determining sensitivity. Only the spectral shape matters, unless forwardSNR=True.

  • nsig (int, float) – Desired nsigma sensitivity (default 10).

  • units (str) – Output units (defaults to uJy for grisms, nJy for imaging).

  • verbose (bool) – Print result details.

Keyword Arguments
  • forwardSNR (bool) – Find the SNR of the input spectrum instead of sensitivity.

  • zfact (float) – Factor to scale Zodiacal spectrum (default 2.5)

  • ideal_Poisson (bool) – If set to True, use total signal for noise estimate, otherwise MULTIACCUM equation is used.

  • rad_EE (float) – Extraction aperture radius (in pixels) for imaging mode.

  • dw_bin (float) – Delta wavelength for spectral sensitivities (grisms & DHS).

  • ap_spec (int, float) – Instead of dw_bin, specify the spectral extraction aperture in pixels. Takes priority over dw_bin. Value will get rounded up to nearest int.

update_detectors(verbose=False, det_list=None, **kwargs)[source]

Generates a list of detector objects depending on module and channel. This function will get called any time a filter, pupil, mask, or module is modified by the user directly:

>>> nrc = pynrc.NIRCam('F430M', ngroup=10, nint=5)
>>> nrc.filter = 'F444W'

If the user wishes to change any properties of the multiaccum ramp or detector readout mode, pass those arguments through this function rather than creating a whole new NIRCam() instance. For example:

>>> nrc = pynrc.NIRCam('F430M', ngroup=10, nint=5)
>>> nrc.update_detectors(ngroup=2, nint=10, wind_mode='STRIPE', ypix=64)

A dictionary of the keyword settings can be referenced in det_info. This dictionary cannot be modified directly.

Parameters
  • det_list (list, None) – List of detector names (481, 482, etc.) to consider. If not set, then defaults are chosen based on observing mode.

  • verbose (bool) – Print out ramp and detector settings.

Keyword Arguments
  • wind_mode (str) – Window mode type ‘FULL’, ‘STRIPE’, ‘WINDOW’.

  • xpix (int) – Size of window in x-pixels for frame time calculation.

  • ypix (int) – Size of window in y-pixels for frame time calculation.

  • x0 (int) – Lower-left x-coord position of detector window.

  • y0 (int) – Lower-left y-coord position of detector window.

  • read_mode (str) – NIRCam Ramp Readout mode such as ‘RAPID’, ‘BRIGHT1’, etc.

  • nint (int) – Number of integrations (ramps).

  • ngroup (int) – Number of groups in a integration.

  • nf (int) – Number of frames per group.

  • nd1 (int) – Number of drop frame after reset (before first group read).

  • nd2 (int) – Number of drop frames within a group (ie., groupgap).

  • nd3 (int) – Number of drop frames after final read frame in ramp.

  • nr1 (int) – Number of reset frames within first ramp.

  • nr2 (int) – Number of reset frames for subsequent ramps.

update_psf_coeff(fov_pix=None, oversample=None, offset_r=None, offset_theta=None, tel_pupil=None, opd=None, wfe_drift=None, include_si_wfe=None, jitter='gaussian', jitter_sigma=0.007, bar_offset=None, save=None, force=False, **kwargs)[source]

Create new PSF coefficients.

Generates a set of PSF coefficients from a sequence of WebbPSF images. These coefficients can then be used to generate a sequence of monochromatic PSFs (useful if you need to make hundreds of PSFs for slitless grism or DHS observations) that are subsequenty convolved with the the instrument throughput curves and stellar spectrum. The coefficients are stored in psf_coeff attribute.

A corresponding dictionary psf_info is also saved that contains the size of the FoV (in detector pixels) and oversampling factor that was used to generate the coefficients.

While originally created for coronagraphy, grism, and DHS observations, this method is actually pretty quick, so it has become the default for imaging as well.

Parameters
  • fov_pix (int) – Size of the FoV in pixels (real SW or LW pixels). The defaults depend on the type of observation. Odd number place the PSF on the center of the pixel, whereas an even number centers it on the “crosshairs.”

  • oversample (int) – Factor to oversample during WebbPSF calculations. Default 2 for coronagraphy and 4 otherwise.

  • offset_r (float) – Radial offset from the center in arcsec.

  • offset_theta (float) – Position angle for radial offset, in degrees CCW.

  • bar_offset (float or None) – For bar masks, the position along the bar to place the PSF (arcsec). Use offset_bar() for filter-dependent locations. If both bar_offset attribute and bar_offset keyword are None, then decide location based on selected filter. A positive value will move the source to the right when viewing V2 to the left and V3 up. Updates bar_offset attribute and coefficients appropriately.

  • wfe_drift (float) – Wavefront error drift amplitude in nm. Updates wfe_drift attribute and coefficients appropriately.

  • opd (tuple, str, or HDUList) – Tuple (file, slice) or filename or HDUList specifying OPD.

  • include_si_wfe (bool) – Include SI WFE measurements? Default=False.

  • tel_pupil (str or HDUList) – File name or HDUList specifying telescope entrance pupil.

  • jitter (str) – Either ‘gaussian’ or ‘none’.

  • jitter_sigma (float) – If jitter = 'gaussian', then this is the size of the blurring effect.

  • save (bool) – Save the resulting PSF coefficients to a file? (default: True)

  • force (bool) – Forces a recalcuation of PSF even if saved PSF exists. (default: False)