Example yaml Input File¶
Below is an example yaml input file for Mirage. The yaml file used as the primary input to mirage contains a large number of telescope and instrument settings, reference files, and catalogs. The inputs are grouped by section:
- Inst section
- Readout section
- Reffiles section
- nonlin section
- cosmicRay section
- simSignals section
- Telescope section
- newRamp section
- Output section
Inst: instrument: NIRCam #Instrument name mode: imaging #Observation mode (e.g. imaging, WFSS, moving_target) use_JWST_pipeline: False #Use pipeline in data transformations Readout: readpatt: DEEP8 #Readout pattern (RAPID, BRIGHT2, etc) overrides nframe,nskip unless it is not recognized ngroup: 6 #Number of groups in integration nint: 1 #Number of integrations per exposure array_name: NRCB5_FULL #Name of array (FULL, SUB160, SUB64P, etc) filter: F250M #Filter of simulated data (F090W, F322W2, etc) pupil: CLEAR #Pupil element for simulated data (CLEAR, GRISMC, etc) Reffiles: #Set to None or leave blank if you wish to skip that step dark: None #Dark current integration used as the base linearized_darkfile: $MIRAGE_DATA/nircam/darks/linearized/B5/Linearized_Dark_and_SBRefpix_NRCNRCBLONG-DARK-60090141241_1_490_SE_2016-01-09T02h46m50_uncal.fits # Linearized dark ramp to use as input. Supercedes dark above badpixmask: $MIRAGE_DATA/nircam/reference_files/badpix/NRCB5_17161_BPM_ISIMCV3_2016-01-21_ssbspmask_DMSorient.fits # If linearized dark is used, populate output DQ extensions using this file superbias: $MIRAGE_DATA/nircam/reference_files/superbias/NRCB5_superbias_from_list_of_biasfiles.list.fits #Superbias file. Set to None or leave blank if not using linearity: $MIRAGE_DATA/nircam/reference_files/linearity/NRCBLONG_17161_LinearityCoeff_ADU0_2016-05-22_ssblinearity_v2_DMSorient.fits #linearity correction coefficients saturation: $MIRAGE_DATA/nircam/reference_files/saturation/NRCB5_17161_WellDepthADU_2016-03-10_ssbsaturation_wfact_DMSorient.fits #well depth reference files gain: $MIRAGE_DATA/nircam/reference_files/gain/NRCB5_17161_Gain_ISIMCV3_2016-02-25_ssbgain_DMSorient.fits #Gain map pixelflat: None illumflat: None #Illumination flat field file astrometric: $MIRAGE_DATA/nircam/reference_files/distortion/NRCB5_FULL_distortion.asdf #Astrometric distortion file (asdf) ipc: $MIRAGE_DATA/nircam/reference_files/ipc/NRCB5_17161_IPCDeconvolutionKernel_2016-03-18_ssbipc_DMSorient.fits #File containing IPC kernel to apply invertIPC: True #Invert the IPC kernel before the convolution. True or False. Use True if the kernel is designed for the removal of IPC effects, like the JWST reference files are. occult: None #Occulting spots correction image pixelAreaMap: $MIRAGE_DATA/nircam/reference_files/pam/NIRCam_B5_PAM_imaging.fits #Pixel area map for the detector. Used to introduce distortion into the output ramp. subarray_defs: config #File that contains a list of all possible subarray names and coordinates readpattdefs: config #File that contains a list of all possible readout pattern names and associated NFRAME/NSKIP values crosstalk: config #File containing crosstalk coefficients filtpupilcombo: config #File that lists the filter wheel element / pupil wheel element combinations. Used only in writing output file flux_cal: config #File that lists flux conversion factor and pivot wavelength for each filter. Only used when making direct image outputs to be fed into the grism disperser code. nonlin: limit: 60000.0 #Upper singal limit to which nonlinearity is applied (ADU) accuracy: 0.000001 #Non-linearity accuracy threshold maxiter: 10 #Maximum number of iterations to use when applying non-linearity robberto: False #Use Massimo Robberto type non-linearity coefficients cosmicRay: path: $MIRAGE_DATA/nircam/cosmic_ray_library/ #Path to CR library library: SUNMIN #Type of cosmic rayenvironment (SUNMAX, SUNMIN, FLARE) scale: 1.5 #Cosmic ray rate scaling factor suffix: IPC_NIRCam_B5 #Suffix of library file names seed: 2956411739 #Seed for random number generator simSignals: pointsource: my_point_sources.cat #File containing a list of point sources to add (x,y locations and magnitudes) psfpath: $MIRAGE_DATA/nircam/webbpsf_library/ #Path to PSF library psfbasename: nircam #Basename of the files in the psf library psfpixfrac: 0.25 #Fraction of a pixel between entries in PSF library (e.g. 0.25 = files for PSF centered at 0.25 pixel intervals within pixel) psfwfe: predicted #PSF WFE value ("predicted" or "requirements") psfwfegroup: 0 #WFE realization group (0 to 4) galaxyListFile: my_galaxies_catalog.list extended: None #Extended emission count rate image file name extendedscale: 1.0 #Scaling factor for extended emission image extendedCenter: 1024,1024 #x,y pixel location at which to place the extended image if it is smaller than the output array size PSFConvolveExtended: True #Convolve the extended image with the PSF before adding to the output image (True or False) movingTargetList: None #Name of file containing a list of point source moving targets (e.g. KBOs, asteroids) to add. movingTargetSersic: None #ascii file containing a list of 2D sersic profiles to have moving through the field movingTargetExtended: None #ascii file containing a list of stamp images to add as moving targets (planets, moons, etc) movingTargetConvolveExtended: True #convolve the extended moving targets with PSF before adding. movingTargetToTrack: None #File containing a single moving target which JWST will track during observation (e.g. a planet, moon, KBO, asteroid) This file will only be used if mode is set to "moving_target" zodiacal: None #Zodiacal light count rate image file zodiscale: 1.0 #Zodi scaling factor scattered: None #Scattered light count rate image file scatteredscale: 1.0 #Scattered light scaling factor bkgdrate: medium #Constant background count rate (electrons/sec/pixel) poissonseed: 2012872553 #Random number generator seed for Poisson simulation) photonyield: True #Apply photon yield in simulation pymethod: True #Use double Poisson simulation for photon yield Telescope: ra: 53.1 #RA of simulated pointing dec: -27.8 #Dec of simulated pointing rotation: 0.0 #y axis rotation (degrees E of N) newRamp: dq_configfile: config #config file used by JWST pipeline sat_configfile: config #config file used by JWST pipeline superbias_configfile: config #config file used by JWST pipeline refpix_configfile: config #config file used by JWST pipeline linear_configfile: config #config file used by JWST pipeline Output: file: jw42424024002_0112o_NRCB5_uncal.fits # Output filename directory: ./ # Directory in which to place output files datatype: linear,raw # Type of data to save. 'linear' for linearized ramp. 'raw' for raw ramp. 'linear,raw' for both format: DMS # Output file format Options: DMS, SSR(not yet implemented) save_intermediates: False # Save intermediate products separately (point source image, etc) grism_source_image: False # Create an image to be dispersed? unsigned: True # Output unsigned integers? (0-65535 if true. -32768 to 32768 if false) dmsOrient: True # Output in DMS orientation (vs. fitswriter orientation). program_number: 42424 # Program Number title: Supernovae and Black Holes Near Hyperspatial Bypasses #Program title PI_Name: Doug Adams # Proposal PI Name Proposal_category: GO # Proposal category Science_category: Cosmology # Science category observation_number: '002' # Observation Number observation_label: Obs2 # User-generated observation Label visit_number: '024' # Visit Number visit_group: '01' # Visit Group visit_id: '42424024002' # Visit ID sequence_id: '2' # Sequence ID activity_id: '2o' # Activity ID. Increment with each exposure. exposure_number: '00001' # Exposure Number obs_id: 'V42424024002P000000000112o' # Observation ID number date_obs: '2019-10-15' # Date of observation time_obs: '06:29:11.852' # Time of observation obs_template: 'NIRCam Imaging' # Observation template primary_dither_type: NONE # Primary dither pattern name total_primary_dither_positions: 1 # Total number of primary dither positions primary_dither_position: 1 # Primary dither position number subpix_dither_type: 2-POINT-MEDIUM-WITH-NIRISS #Subpixel dither pattern name total_subpix_dither_positions: 2 # Total number of subpixel dither positions subpix_dither_position: 2 # Subpixel dither position number xoffset: 344.284 # Dither pointing offset in x (arcsec) yoffset: 466.768 # Dither pointing offset in y (arcsec)
This section of the input yaml file contains information about the instrument being simulated.
The name of the JWST instrument to be simulated. The simulator will only function if ‘NIRCam’, ‘NIRISS’, or ‘FGS’ is placed in this field.
The observing mode to be simulated. There are three valid options for this field. “imaging” will create imaging data, “wfss” will produce wide field slitless spectroscopic data. The other accepted input is “ami” when simulating NIRISS, although this mode is functionally identical to the use of “imaging”.
Create data using JWST pipeline¶
True/False. Set to False if you wish to proceed without using any JWST pipeline functions. In this case, the input dark current exposure must already be linearized, as the pipeline is used for the linearization process. True is recommneded.
This section of the yaml file contains inputs describing the details of the exposure, including the readout pattern, filter, subarray, etc to use.
This is the name of the readout timing pattern used for the output simulated exposure. Examples for NIRCam include RAPID, BRIGHT1, BRIGHT2, and DEEP8. Each pattern averages and skips a predefined number of frames when constructing each group of an integration. The list of possible readout patterns and their definitions is provided by an ascii file specified in the readpattdefs parameter in the Reffiles section of the input file. A more detailed description of readout patterns is given in the detector readout pages for NIRCam, NIRISS, and FGS.
Number of groups per integration¶
This parameter lists the number of groups comprising each output integration.
Number of integrations per exposure¶
The number of integrations in the output exposure. Each integration is composed of ngroup groups. Note that currently, any observation containing a moving target (non-sidereal observation with trailed sidereal objects, or vice versa) cannot have an nint value greater than 1. (IS THIS STILL TRUE?)
Number of detector resets between integrations¶
The number of detector resets between integrations within a single exposure. For all instruments, this should be set to 1.
This is the name of the aperture used for the simulated data. Generally, this is composed of the name of the detector combined with the name of the subarray used. For example, a full frame observation using NIRCam’s A1 detector has an array_name of ‘NRCA1_FULL’, while a full frame NIRISS observation will have an array_name of ‘NIS_CEN’. The list of possible array_name values are given in the subarray_defs input file described below. The array_name is used to identify several other characteristics of the simulated data, including the detector to use, as well as the proper array dimensions and location on the detector.
The name of the filter wheel element to use for the simulated data. (e.g. F444W). The filter is used when scaling astronomical sources from the requested brightness in magnitudes to counts on the detector. For NIRCam simulations, the filter name is also used to determine whether the simulated data are to be produced using a shortwave or longwave detector. Lists of instrument filters can be found on the NIRCam, NIRISS, and FGS filter pages.
The name of the pupil wheel element to use for the simulated data. Some filters for both NIRCam and NIRISS reside in their respective pupil wheels. Therefore this entry is checked when deciding upon scaling factors for simulated sources. Pupil wheel elements are desribed in the NIRCam, NIRISS, and FGS pupil wheel pages.
This section of the input file lists the various reference files needed for the various steps of the simulator to run.
Dark current exposure¶
The name of the raw dark current file that will be used as the basis for the simulated exposure. This file must be in raw format, such that no JWST calibration pipeline steps have been applied to the data. If an already-linearized dark current integration is to be used, that file name should be placed in the linearized_darkfile field below. Note that the linearized_darkfile entry will take precedence. Only if that is set to __None__ will the file listed in this field be used.
The dark current integration must have a readout pattern of either RAPID/NISRAPID/FGSRAPID or a value identical to that of the integration to be simulated. RAPID/NISRAPID/FGSRAPID data keep every readout frame with no averaging. From this, any other readout pattern can be simulated by averaging and skipping the appropriate frames. Other readout patterns cannot be translated in this way as their data are already averaged or missing some frames. However if simulating, for example a BRIGHT2 integration, then the input dark current integration can be a BRIGHT2 integration, as no translation is necessary in this case.
If a translation between RAPID and another readout pattern is necessary, then frames will be averaged/skipped as necessary. If the input dark current integration does not contain enough frames to be translated into the requested number of output groups, then the script creates enough additional dark current frames to make up the difference. These additional frames are created by making a copy of an appropriate number of existing initial dark current frames, and adding their signals to that in the final dark current frame. Note that this can lead to apparent double cosmic rays in pixels where a cosmic ray appeared in the dark current integration.
This input can only be used if use_JWST_pipeline is set to True.
The collection of reference files associated with Mirage contains a small library of raw dark current exposures that can be used.
Linearized dark current exposure¶
The name of a linearized dark current integration to use as input for the simulated data. This file should contain a dark integration that has been processed through the superbias subtraction, reference pixel subtraction, and linearity steps of the JWST calibration pipeline. The resulting linearized signal must be saved in an extension with the name ‘SCI’. Also, the subtracted signal from the superbias and reference pixels must be saved in an extension called ‘SBANDREFPIX’. This output will be produced and saved for a given dark current file by Mirage.
Using this input rather than the uncalibrated dark above can save significant computing time, especially in the case of creating many output exposures.
This input can be used for use_JWST_pipeline set to True or False.
The collection of reference files associated with Mirage contains a small library of linearized dark current products that can be used.
Bad pixel mask¶
If a linearized dark current file is to be used and a linearized output file is requested, this optional bad pixel mask can be used to populate the data quality array in the output simulated data file. The file must be in the format for JWST bad pixel masks that is used by the JWST calibration pipeline.
The collection of reference files associated with Mirage contains a library of bad pixel masks that can be used.
The superbias reference file for the detector of the simulation. This file must match the format of the JWST pipeline superbias reference file. If the input dark current integration is a raw file then this superbias file is used to subtract the superbias from the dark. If the input dark is already linearized, this superbias file is not used.
The collection of reference files associated with Mirage contains a library of superbias files that can be used.
Linearity correction coefficients¶
Name of the reference file containing the linearity correction coefficients. This file must be in the format expected by the JWST calibration pipeline. If the input dark current integration is raw, the coefficients contained in this file are used to linearize the dark current after subtracting the superbias and reference pixel signal. These coefficients are also used to “unlinearize” the final simulated exposure if a raw simulated observation is requested.
In addition, the coefficients in this file are used to linearize the values in the saturation reference file, such that saturated signals in the linear simulated exposure can be found.
The collection of reference files associated with Mirage contains a library of linearity coefficient files that can be used.
Name of the reference file containing a map of the saturation signal level for all pixels. If the input dark current integration is raw, this file is used by the calibration pipeline to flag saturated pixels in the dark current integration prior to linearizing. The format of this file must match that used in the saturation flagging step of the JWST calibration pipeline.
This saturation map, after being linearized, is also used to search for saturated signal values in the combined dark current/simulated source exposure prior to unlinearizing.
The collection of reference files associated with Mirage contains a library of saturation map files that can be used.
Name of the file containing the gain map appropriate for the detector being used. The gain is used to translate the cosmic rays, which are in units of electrons, to units of ADU prior to adding them to the simulated data. The format of the gain file must match that used by the JWST calibration pipeline.
The collection of reference files associated with Mirage contains a library of gain map files that can be used.
Pixel-to-pixel flat field image¶
Name of the pixel flat file to use. Once the simulated integration is created, the result is multiplied by the pixel flat. This is done to un-flatten the image.
Illumination flat (L-flat)¶
Name of the illumination flat to use. Once the simulated integration is created, the result is multiplied by the illumination flat.
Astrometric distortion file¶
Name of the astrometric distortion reference file to use for including the effects of distortion in the simulated data. This file is used to translate input source locations between RA and Dec coordinates and pixel x and y coordinates, and vice versa. This file must be in asdf format and match that expected by the calibration pipeline.
The collection of reference files associated with Mirage contains a library of distortion reference files that can be used.
Interpixel capacitance (IPC)¶
File containing the interpixel capacitance (IPC) kernel to apply to the simulated data in order to introduce IPC effects. After all simulated objects have been added to a count rate image, the image is convolved with the IPC kernel. The IPC file must be a fits file with the IPC kernel located in the first (rather than 0th) extension. Typical JWST IPC reference file kernels are a 3x3 array, but Mirage supports kernels of any odd-numbered size, as well as 4-dimensional kernels, where there is a separate 2-dimensional kernel for each pixel. In order to introduce, rather than remove, IPC effects, the kernel must be normalized and have a value in the central pixel which is less than 1.0. This is the inverse of the kernel used in the JWST calibration pipeline IPC removal step, where the central pixel has a value greater than 1.0, and negative values in surrounding pixels. For the simulator, the user can specify a JWST calibration pipeline-formatted kernel file, and then set the invertIPC flag below to True, in which case the kernel will be inverted before using.
The collection of reference files associated with Mirage contains a library of IPC kernel files that can be used.
If set to True, the IPC kernel supplied through the ipc entry is inverted before convolving with the signal rate image. JWST IPC kernel reference files contain the kernel necessary to remove IPC from the data. Therefore these kernels must be inverted before they can add IPC effects to the data in the simulator.
Occulting spot image¶
This feature is not yet supported and should be set to None.
Pixel area map¶
Fits file containing the pixel area map for the detector to be simulated. If provided, the pixel area map is multiplied into the seed image at a point when the seed image contains only extended sources. Point sources have the pixel area map applied to them at the time the PSF libraries were created via webbpsf. The pixel area map file must be in the format of the JWST pixel area map reference file.
The collection of reference files associated with Mirage contains a library of pixel area map files that can be used.
Subarray definition file¶
Name of a whitespace-delimited ascii file that lists all of the possible supported subarray apertures. This file is provided with the MIRAGE repository, in the config subdirectory.
To use the subarray definition files packaged with Mirage, set this to config in the input yaml file. This is the default when creating yaml files from an APT file using the yaml generator
For each subarray, the file must list the full aperture name (e.g. NRCA1_FULL) as well as the corresponding name used in proposal planning (e.g. FULL), as well as the number of amplifiers used to read out each aperture.
Readout pattern definition file¶
Ascii file which gives the definitions of the possible readout patterns for the instrument. For each readout pattern, the number of frames averaged to create each group (nframe) and the number of frames skipped beteren each group (nskip) must be specified, as well as the maximum number of allowed groups. For a given readout pattern the simulator will search the entries in this file in order to determine the proper nframe and nskip values to use. The current lists of acceptable NIRCam and NIRISS readout patterns are given on the NIRCam and NIRISS detector readouts webpages. These files for all instruments are provided with the MIRAGE repository, in the config subdirectory.
To use the readout pattern definition files packaged with Mirage, set this to config in the input yaml file. This is the default when creating yaml files from an APT file using the yaml generator
Ascii file containing crosstalk coefficients. Crosstalk is only applied to data read out through more than one amplifer. The file contains one row for each detector. Each row contains all of the coefficients necessary to fully describe crosstalk. This file is contained in the MIRAGE repository, in the config subdirectory.
To use the crosstalk coefficient files packaged with Mirage, set this to config in the input yaml file. This is the default when creating yaml files from an APT file using the yaml generator
Allowed filter/pupil combinations¶
Name of an ascii file containing a list of the filter and pupil wheel elements in place when requesting simulated data for a given filter. This information is used to apply the appropriate conversion between magnitudes and counts when reading in source catalogs. This flux calibration is also added to the header of the seed image, as it is used when seed images are dispersed during the simulation of WFSS data. This file is present in the config subdirectory of the MIRAGE repository.
To use the filter and pupil wheel definition files packaged with Mirage, set this to config in the input yaml file. This is the default when creating yaml files from an APT file using the yaml generator
Ascii file that lists flux conversion factors and the pivot wavelength associated with each filter. Conversion factors include ABMAG, STMAG, and VEGAMAG to counts per second, as well as FLAM (erg s -1 cm -2 Å -1 and FNU (erg s -1 cm -2 Hz -1 to counts per second. This file is used when producing seed images to be fed into the grism disperser code, as well as for translating catalog sources from magnitudes to counts per second. This file is provided with the MIRAGE repository, in the config subdirectory.
To use the flux calibration files packaged with Mirage, set this to config in the input yaml file. This is the default when creating yaml files from an APT file using the yaml generator
The following input fields describe how non-linearity is treated in the input and simulated data.
Signal limit, in units of ADU, above which the linearity correction is not applied. Pixels with signals above this limit are considered saturated. This single value across the entire detector is only used if a saturation reference file is not provided.
When introducing non-linearity back into the linear data, the Newton-Raphson method is used to essentially run the JWST calibration pipline’s linearity correction step in reverse. The value of this accuracy parameter is the threshold below which the solution is considered to have converged. For example, an accuracy threshold of 0.000001 means that the unlinearization is considered complete when the ratio of the signal values from one iteration to the next is less than 1.000001.
Maximum number of iterations¶
The maximum number of iterations of the Newton-Raphson method to use when introducing non-linearity back into the data before declaring failure. Default is 10.
If set to False, the simulator assumes that the non-linearity correction function and coefficients match those used in the JWST calibration pipeline. If set to True, the script assumes an alternate linearity function, as defined in Robberto (2010 , 2011). Currently, no coefficients for the latter method exist, implying this parameter should be set to False.
Cosmic ray section¶
Input parameters in this section describe how cosmic rays are added to the simulated data.
Path to cosmic ray library¶
Path of the location of the cosmic ray library to use. The code was developed around the cosmic ray library produced by Robberto (2009). This library is included in the collection of reference files associated with Mirage. After extracting the library from the tar file, set this path to point to the top level directory of the cosmic ray library.
Specification of which cosmic ray library to choose cosmic rays from. Options are SUNMIN, SUNMAX, FLARE, each of which assumes a different cosmic ray rate. Details on the three types of libraries are given in Robberto (2009).
Scaling value for rate¶
Scaling factor to apply to the cosmic ray rate. For example, to simulate cosmic rays at a rate twice as high as that in SUNMIN, set library to SUNMIN and scale to 2.0
Filename suffix of the cosmic ray library files. The code was developed around files with the suffix of ‘IPC_NIRCam_XX’ where XX is the detector (e.g. B5) for NIRCam, ‘IPC_NIRISS_NIS’ for NIRISS, and ‘IPC_FGS_GUIDERy’ where y is 1 or 2, for FGS. These cosmic ray files are included in Mirage’s reference file collection. This field will be automatically populated with the correct suffix when creating yaml files using the yaml generator.
Seed for random number generator¶
Random number generator seed to use when selecting cosmic rays to add.
This section of the input file describes how sources and other signals are added to the simulated data.
Point source catalog file¶
PSF library path¶
Path name to the PSF library to be used for adding point sources to the data. The code was developed around a PSF library constructed using WebbPSF (Perrin, 2014). This PSF library is included in the collection of Mirage reference files . Once that package is downloaded and the data files extracted from the tar file, set this field to point to the top-level directory of the PSF library.
PSF library file basename¶
Basename of the files in the PSF library. When using the default libraries that are distributed with Mirage, this should be set to the name of the instrument.
Sub-pixel grid resolution of PSF library¶
It is assumed that the PSF library contains a grid of PSFs centered at various sub-pixel locations. This parameter specifies the resolution of this grid. For example, if the library contains PSFs centered at every 0.25 pixels across a pixel in x and y, then this field should be set to 0.25. In the current collection of Mirage reference files the PSF library for NIRCam uses a resolution of 0.25, while those for NIRISS and FGS have a resolution of 0.1 pixels.
PSF library wavefront error¶
PSF wavefront error value to use when choosing PSF files from the PSF library. The current PSF libraries distributed with the Mirage reference files have two options for wavefront error: “predicted” and “requirements”. These two values represent the predicted in-flight wavefront errors, and the maximum allowed wavefront errors, respectively.
PSF realization number¶
The current PSF library contains 5 different realizations for each filter/wavefront error-specified PSF. In this field, place the realization number to use. With 5 realizations present in the library, this field can have a value of 0 through 4.
Galaxy source catalog file¶
Extended source catalog file¶
Name of an ascii file containing a list of “extended images” to add to the simulated data. These are stamp image of sources, contained in small fits files. These stamp images are read in, scaled to the requested magnitude, and added to the seed image. This is a way to add objects other than point sources or 2D Sersic profiles to the data. The extended catalog section of the catalogs page shows an example extended source catalog.
Extended source scaling factor¶
Multiplicative factor by which to scale the data in the extended image file before adding to the simulated data. The extended image is multiplied by this factor if the magnitude is set to None in the extended catalog file.
Extended source center location¶
In the case where a single extended source is provided, this entry can be set to the (x,y) pixel location at which to place the center of the exteded image. This functionality is largely replaced by specifying the RA, Dec or x, y of the extended image in the extended source catalog file.
Convolve extended sources with PSF¶
True/False. Convolve the extended image with the appropriate instrumental PSF prior to adding to the output image.
Moving target source catalog file¶
Similar to the point source list file, this is a file containing a list of targets to treat as moving (non-sidereal) targets. These sources will move through the field of view as the exposure progresses. This is the list to use if you wish to insert an asteroid or KBO that is moving through the field of view of your observation. See the moving point source section on the Catalogs page for an example.
2D Sersic profile moving target catalog file¶
Similar to the galaxy target list file, this file contains a list of galaxies (2D Sersic profiles) to be used as moving targets. These sources will move through the background of the simulated data. This may be useful for inserting a resolved moon/asteroid into the scene. An example file is shown in the Moving Sersic section of the Catalogs page.
Moving extended source catalog file¶
Similar to the extended target list, this is an ascii file listing extended targets to move through the background of the image. A description and example of this file are shown in the Moving Extended section of the Catalogs page.
Convolve moving extended targets with PSF¶
Set this input to True if you wish to convolve the images listed in movingTargetExtended with the instrumental PSF prior to adding them to the simulated data.
Tracked non-sidereal target catalog file¶
This ascii catalog file is used for what are traditionally (in HST jargon) called ‘moving targets’. Targets listed in this file are treated as non-sidereal targets that JWST will track during the simulated observation. In this case, the target listed in this file will appear static in the output data, but all other sources (e.g. those listed in pointSource, galaxyListFile, and extended) will all appear trailed through the data. A description and example of the file are shown in the Non-sidereal Source section on the Catalogs page.
This keyword has been depricated in favor of obtaining the zodiacal light from the JWST backgrounds package.
Name of a file containing a 2 dimensional count rate image of zodiacal light. This file is read in, scaled by the zodiscale value, and added to the seed image. Leave as None to skip this step. The behaviors of this step and the scattered step below are very basic, and identical. There are no requirements on what the count rate images in these files must look like.
Note that the bkgdrate input parameter, when set to “high”, “medium”, or “low”, will return a background rate image that includes the contribution from zodiacal light, in which case this step should be set to None.
Scaling factor for zodiacal light image¶
Scaling factor to multiply the zodiacal light count rate image by prior to adding to the output data.
Scattered light image¶
This keyword is currently not supported.
Scattered light count rate image file. This file is assumed to contain a 2-dimensional array of signals in units of ADU per second. The file is read in, scaled by the scatteredscale value, and added to the seed image. Leave as None to skip this step.
Scattered light scaling factor¶
Scaling factor to multiply the scattered light count rate image by prior to adding to the seed image.
There are two options when specifying the background rate with this keyword:
- When a number is provided, a constant (across all pixels) background count rate is added to the output data. The value is assumed to have units of counts per pixel per second.
- Alternately, the value can be “high”, “medium”, or “low”. If one of these options is used, the simulator uses the jwst_backgrounds repository to calculate the background rate to apply to the simulated data. The package calculates the background signal at the requested pointing on the sky for each night over the course of a year and creates a histogram of these values. If the requested background is “low” then the returned background level is equal to that of the 10th percentile in the histogram. A “medium” background corresponds to the 50th percentile value, and “high” is the 90th percentile value. In this case, the returned background rate includes contributions from zodiacal light and telescope thermal emission.
Note that background rates associated with the “low”, “medium”, and “high” values are calculated in the same way as when they are used in the JWST ETC.
Seed value for poisson noise generator¶
Random number generator seed used for Poisson simulation
This keyword is currently not used. T/F. Set this to True to include the effects of photon yield in the simulation outputs.
Photon yield method¶
This keyword is currently not used. T/F. Whether or not to use the double photon method when applying photon yield.
Inputs in this section of the yaml file describe the telescope pointing to use for the simulation.
Right ascension of the observation. This will be the RA at the reference location on the detector being used for the simulation. The reference location varies with the requested subarray, but is generally in the center of the field of view. This input can be a string “HH:MM:SS.sss”, or a float in decimal degrees.
Declination of the observation. This will be the Dec at the reference location on the detector. The reference location varies with the requested subarray, but is generally in the center of the field of view. This input can be a string “DD:MM:SS.sss” or a float in decimal degrees.
Rotation of the y-axis in degrees East of North. Currently this rotation is defined around the reference location of the chosen subarray.
This section of the input file lists JWST calibration pipeline-style configuration files that may be needed when preparing the simulated data. Copies of all of these configuration files are included in the ‘config’ subdirectory of the MIRAGE repository. Therefore, unless you wish to use your own set of configuration files, you can set these fields all to ‘config’. This is the default behavior when creating yaml files via the yaml generator.
In order to create your own set of pipeline configuration files, use the shell command:
> collect_pipeline_cfg /your/destination/directory
DQ step configuration file¶
Name of the JWST calibration pipeline configuration file to be used in the dq_init step when it is run on the raw dark current integration.
Saturation step configuration file¶
Name of the JWST calibration pipeline configuration file to be used in the saturation step when it is run on the raw dark current integration.
Superbias step configuration file¶
Name of the JWST calibration pipeline configuration file to be used in the superbias step when it is run on the raw dark current integration.
Reference pixel subtraction configuration file¶
Name of the JWST calibration pipeline configuration file to be used in the reference pixel subtraction step when it is run on the raw dark current integration.
If you choose to use your own reference pixel correction configuration file, we recommend setting the odd_even_rows entry to False, as this correction is not typically performed on NIRCam, NISISS, or FGS data.
Linearity step configuration file¶
Name of the JWST calibration pipeline configuration file to be used in the linearity correction step when it is run on the raw dark current integration.
This section of the yaml file contains information about the output file, such as filename and location. In addition, this section contains a large number of fields that describe how this particular exposure fits within an observing program/proposal. This information is not used during the creation of the simulated data, but is placed in the header of the output file in order to be consistent with the contents of real JWST data files. In addition, level 3 of the JWST calibration pipeline, which is used to combine multiple exposures into mosaic images, does require some of this information. The easiest way to correctly populate this information in the simulator yaml files is to create the yaml files from an APT file via yaml_generator.py, in which case the fields are all populated automatically.
Filename of the output simulated file (e.g. jw42424024002_01101_00001_nrcb5_uncal.fits). If the linearized ramp is requested as output in the datatype field, it will be saved with ‘uncal’ replaced with ‘linear’ in the filename or if ‘uncal’ is not present, ‘linear’ will simply be appended to the filename. If the raw ramp is requested as output, the given filename will be used with no changes.
We recommend using filenames that end in ‘uncal.fits’ in order to be consistent with JWST file naming conventions. The filename is constructed from various pieces of information, including the program ID and visit number. If you wish to use this convention for the output filenames, the easiest way to accomplish this is to create the yaml files from an APT file, in which case the filenames will be generated automatically.
The directory into which the output simulated data will be placed.
List of the data format(s) of the output files. Options include: “linear”, where the output files will contain linearized signals with the superbias and reference pixel signals removed. Bad pixels will also be flagged if a bad pixel file is specified. These files are ready to be run through the jump detection and ramp fitting steps of the JWST calibration pipeline. “raw”, where the output files will be in an uncalibrated state. These files are ready to be run through the entirety of the calibration pipeline, beginning with calwebb_detector1. “linear,raw”, where both the raw and linearized versions of the output files will be saved.
Format of the output file. Currently, only ‘DMS’ is supported, indicating that the fits file format, as well as header keywords, match those expected by the JWST calibration pipeline.
Save intermediate outputs¶
True/False. If True, intermediate products are saved to disk. These products are listed in the table below.
|Module||Suffix Appended to Output Filename||Description|
|Seed Image Generator||_pointsources.list||Ascii file listing point source x,y and RA, Dec positions as well as magnitude and count rate.|
|_galaxySources.list||Ascii file listing galaxy source x,y and RA, Dec positions, morphology parameters, magnitudes, and count rates.|
|_extendedsources.list||Ascii file listing extended source x,y and RA, Dec positions as well as magnitude and count rate.|
|_pointSourceRateImage_elec_per_sec.fits||Count rate image containing only added point sources|
|_galaxyRateImage_elec_per_sec.fits||Count rate image containing only added galaxies|
|_extendedObject_elec_per_sec.fits||Count rate image containing only extended objects|
|_AddedSources_elec_per_sec.fits||Count rate image containing all added sources|
|Observation Generator||_doNonLin_accuracy.fits||Final accuracy map from the process where the linearized simulated exposure was “unlinearized”|
|_xtalk_correction_image.fits||Image of the crosstalk signal added to the exposure|
|_cosmicrays.list||Ascii file containing location and magnitude of added cosmic rays|
Grism output image¶
True/False. If True, the size of the output image is enlarged from the requested array size by a multiplicative factor in the x and y dimensions. For NIRCam this factor is √2, while it NIRISS it is 1.134. This extra area is required if the image is passed to the grism disperser software. In this case, the disperser software is able to include sources which fall just outside the nominal field of view but whose dispersed spectra fall into the nominal field of view.
Outputs in unsigned integers¶
T/F. If True, output signal values for raw data will be in units of unsigned integers. This matches the output of real JWST data.
Output data in DMS orientation¶
T/F. If True, data will be output in DMS orientation, as opposed to raw FITSwriter orientation. JWST data will be in DMS orientation.
The proposal ID number. This is placed in the header of the output file in order to match the contents of real observation files.
The title of the proposal. This placed in the header of the output file in order to match the contents of real observation files.
Name of the proposal PI. This is placed in the header of the output file in order to match the contents of real observation files.
Proposal category (e.g. GO, GTO). This is placed in the header of the output file in order to match the contents of real observation files.
Science category of the proposal, as defined in the APT file. This is placed in the header of the output file in order to match the contents of real observation files.
The observation number containing the output exposure, as defined in the program’s APT file. This is placed in the header of the output file in order to match the contents of real observation files.
The observation label in the APT file under which the output exposure appears. This is placed in the header of the output file in order to match the contents of real observation files.
The visit number, as defined in the APT file, within which the output exposure appears. This is placed in the header of the output file in order to match the contents of real observation files.
Visit group number¶
The visit group, as defined in the APT file, within which the output exposure appears. This is placed in the header of the output file in order to match the contents of real observation files.
Visit ID number¶
The visit identifier of the exposure. This can be created by combining the program ID, visit number, and observation number. This is placed in the header of the output file in order to match the contents of real observation files.
The parallel sequence identifier denotes whether the data were acquired during parallel observations, and with which instrument. Set to 0 for non-parallel observations, 1 for a parallel sequence using the primary instrument, or 2-5 for one of the non-prime instruments.
The activity identifier of the exposure is a base-36 number that is unique to each exposure in a proposal. This is placed in the header of the output file in order to match the contents of real observation files.
A five-character number used to identify the exposure within the current activity.
The observation ID is constructed from several of the other parameters. OBS_ID = ‘V’ + program_number + observation_id + visit_id + ‘P’ + parallel-program number + parallel-observation number + visit_group + parallel sequence identifier + activity_identifier.
UTC date of the start of the exposure with format yyyy-mm-dd.
UTC time of the start of the exposure with format hh:mm:ss.ssssss.
The name of the observation template used for the exposure (e.g. NIRCam Imaging, NIRCam Time Series)
Primary dither type¶
Number of primary dither positions¶
Total number of primary dither positions in the observation.
Primary dither position¶
Primary dither position number of the exposure being simulated.
Subpixel dither type¶
Name of the subpixel dither pattern used for these data. Details on subpixel dither patterns can be found on the NIRCam subpixel dither patterns page.
Number of subpixel dither positions¶
Total number of subpixel dither positions for this observation.
Subpixel dither position¶
The subpixel dither position number corresponding to the current exposure.
Offset in the x direction, in arcseconds, of the pointing used for the current exposure relative to the starting position of the dither pattern. This is used to populate header values only. It is not used to determine the pointing when creating the simulated data.
Offset in the y direction, in arcseconds, of the pointing used for the current exposure relative to the starting position of the dither pattern. This is used to populate header values only. It is not used to determine the pointing when creating the simulated data.