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:
newRamp section
Inst: instrument: NIRCam #Instrument name mode: imaging #Observation mode (e.g. imaging, wfss) 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) intermediate_aperture: None # Name of intermediate aperture used in NIRCam Grism time series obs. PPS_aperture: NRCB5_FULL # Original aperture value supplied by PPS. 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: crds # If linearized dark is used, populate output DQ extensions using this file superbias: crds #Superbias file. Set to None or leave blank if not using linearity: crds #linearity correction coefficients saturation: crds #well depth reference files gain: crds #Gain map pixelflat: None illumflat: None #Illumination flat field file astrometric: crds #Astrometric distortion file (asdf) photom: crds #Cal pipeline photom reference file ipc: crds #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 transmission: crds # Transmission image containing fractional throughput map. (e.g. to imprint occulters into fov 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 filter_wheel_positions: 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. filter_throughput: /Users/me/mirage/mirage/config/placeholder.txt #File containing filter throughput curve 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/gridded_psf_library/ #Path to PSF library gridded_psf_library_row_padding: 4 # Number of outer rows and columns to avoid when evaluating library. RECOMMEND 4. psf_wing_threshold_file: config # File defining PSF sizes versus magnitude add_psf_wings: True # Whether or not to place the core of the psf from the gridded library into an image of the wings before adding. 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) movingTargetToTrack: None #Catalog 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 tracking is set to "non-sidereal" tso_imaging_catalog: None #Catalog listing TSO source to be used for imaging TSO simulations tso_grism_catalog: None #Catalog listing TSO source to be used for grism TSO observations 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 (ADU/sec/pixel in an undispersed image) or "high","medium","low" similar to what is used in the ETC 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 expand_catalog_for_segments: False # Expand catalog for 18 segments and use distinct PSFs use_dateobs_for_background: False # Use date_obs value to determine background. If False, bkgdrate is used. signal_low_limit_for_segmap: 0.031 # Lower signal limit for a pixel to be included in the segmentation map signal_low_limit_for_segmap_units: ADU/sec # Units of signal_low_limit_for_segmap. Can be: ADU/sec, e/sec, MJy/sr, ergs/cm2/a, ergs/cm2/hz add_ghosts: True # Add optical ghosts to simulation PSFConvolveGhosts: False # Convolve ghost sources with instrument PSF before adding 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) tracking: sidereal #sidereal or non-sidereal Output: file: jw42424024002_01101_00001_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 target_name: TARG1 # Name of target target_ra: 53.1001 # RA of the target, from APT file. target_dec: -27.799 # Dec of the target, from APT file. 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: '1' # Sequence ID activity_id: '01' # Activity ID. Increment with each exposure. exposure_number: '00001' # Exposure Number obs_id: 'V42424024002P0000000001101' # 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)
Instrument secton¶
This section of the input yaml file contains information about the instrument being simulated.
Instrument Name¶
Inst:instrument
The name of the JWST instrument to be simulated. The simulator will only function if ‘NIRCam’, ‘NIRISS’, or ‘FGS’ is placed in this field.
Observing mode¶
Inst:mode
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¶
Inst:use_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.
Readout section¶
This section of the yaml file contains inputs describing the details of the exposure, including the readout pattern, filter, subarray, etc to use.
Readout pattern¶
Readout:readpatt
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¶
Readout:ngroup
This parameter lists the number of groups comprising each output integration.
Number of integrations per exposure¶
Readout:nint
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¶
Readout:resets_bet_ints
The number of detector resets between integrations within a single exposure. For all instruments, this should be set to 1.
Array Name¶
Readout:array_name
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.
Intermediate Aperture¶
Readout:intermediate_aperture
This is the name of the intermediate aperture designated by APT to control the telescope pointing during Grism Time Series observations. The intermediate aperture specifies the location of the target prior to inserting the grism into the beam. When the grism is placed in the beam, the target’s trace will be offset from this location by a few tens of rows. The intermediate aperture is defined such that the target’s trace will land at the reference location of the user-specified aperture. This is only used for Grism Time Series observations, including the shortwave imaging mode data that accompany the dispersed longwave data. For all other observations, this will be set to None, and ignored.
PPS_aperture¶
Readout:PPS_aperture
This is the name of the aperture as supplied by PPS (i.e. in the APT pointing file). The value of this may include apertures that are not specific to one detector (e.g. NRCBS_FULL).
Filter¶
Readout:filter
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.
Pupil¶
Readout:pupil
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.
Reffiles section¶
This section of the input file lists the various reference files needed for the various steps of the simulator to run.
Dark current exposure¶
Reffiles:dark
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.
Hint
This input can only be used if use_JWST_pipeline is set to True.
Hint
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¶
Reffiles:linearized_darkfile
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.
Hint
This input can be used for use_JWST_pipeline set to True or False.
Hint
The collection of reference files associated with Mirage contains a small library of linearized dark current products that can be used.
Bad pixel mask¶
Reffiles:badpixmask
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.
Hint
Setting this entry equal to ‘crds’ will cause Mirage to query the Calibration Reference Database System (CRDS) for the appropriate file, and download that file if it is not already present in your CRDS cache.
Superbias¶
Reffiles:superbias
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.
Hint
Setting this entry equal to ‘crds’ will cause Mirage to query the Calibration Reference Database System (CRDS) for the appropriate file, and download that file if it is not already present in your CRDS cache.
Linearity correction coefficients¶
Reffiles:linearity
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.
Hint
Setting this entry equal to ‘crds’ will cause Mirage to query the Calibration Reference Database System (CRDS) for the appropriate file, and download that file if it is not already present in your CRDS cache.
Saturation¶
Reffiles:saturaiton
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.
Hint
Setting this entry equal to ‘crds’ will cause Mirage to query the Calibration Reference Database System (CRDS) for the appropriate file, and download that file if it is not already present in your CRDS cache.
Gain¶
Reffiles:gain
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.
Hint
Setting this entry equal to ‘crds’ will cause Mirage to query the Calibration Reference Database System (CRDS) for the appropriate file, and download that file if it is not already present in your CRDS cache.
Pixel-to-pixel flat field image¶
Reffiles:pixelflat
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)¶
Reffiles:illumflat
Name of the illumination flat to use. Once the simulated integration is created, the result is multiplied by the illumination flat.
Astrometric distortion file¶
Reffiles:astrometric
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.
Hint
Setting this entry equal to ‘crds’ will cause Mirage to query the Calibration Reference Database System (CRDS) for the appropriate file, and download that file if it is not already present in your CRDS cache.
Photom Reference File¶
Reffiles:photom
Name of the JWST calibration pipeline photom reference file to use. This file is used to translate the minimum flux level for pixel inclusion in the segmentation map to ADU/sec in the case where the user provides that value in MJy/sr.
Hint
Setting this entry equal to ‘crds’ will cause Mirage to query the Calibration Reference Database System (CRDS) for the appropriate file, and download that file if it is not already present in your CRDS cache.
Interpixel capacitance (IPC)¶
Reffiles: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.
Hint
Setting this entry equal to ‘crds’ will cause Mirage to query the Calibration Reference Database System (CRDS) for the appropriate file, and download that file if it is not already present in your CRDS cache.
Invert IPC¶
Reffiles:invertIPC
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¶
Reffiles:occult
This feature is not yet supported and should be set to None.
Transmission Image¶
Reffiles:transmission
Fits file containing the transmission image for the detector/filter/pupil to be simulated. The values in this image are the transmission fraction for each pixel, and the image is multiplied in to the seed image (prior to dispersing if simulating WFSS data). This image is designed to contain occulters/masks that are present within the field of view.
Hint
Setting this entry equal to ‘crds’ will cause Mirage to get the appropriate file from the collection of Mirage reference files. The ultimate source of these files are the GRISM_NIRCAM and GRISM_NIRISS repositories, which must be cloned from github during the Mirage installation process and placed within the Mirage reference files directory structure. In the future, we anticipate that the transmission files will be hosted by the CRDS system, which is why they are treated similarly to the current CRDS reference files.
Subarray definition file¶
Reffiles:subarray_defs*
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.
Hint
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¶
Reffiles:readpattdefs
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.
Hint
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
Crosstalk¶
Reffiles:crosstalk
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.
Hint
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¶
Reffiles:filtpupilcombo
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.
Hint
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
Filter/Pupil wheel resolver positions for each optical element¶
Reffiles:filter_wheel_positions
Name of an ascii file containing a list of all filter wheel and pupil wheel elements, along with the nominal wheel resolver positions for each. These values are in degrees. This information is passed directly to the header keywords FWCPOS and PWCPOS in the simulated data FITS files. This information is needed to compute the dispersion solution for NIRISS WFSS. Currently the header keywords are only populated for NIRISS observations.
Hint
To use the filter and pupil wheel position 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
Flux calibration¶
Reffiles:flux_cal
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.
Hint
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
Filter Throughput¶
Reffiels:filter_throughput
Ascii files that contains the system throughput when using a particular filter. By default, the yaml generator will set this parameter to have a value of “placeholder.txt” in the input yaml files. Mirage will then locate the appropriate throughput file at runtime.
Nonlin section¶
The following input fields describe how non-linearity is treated in the input and simulated data.
Limiting Signal¶
nonlin:limit
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.
Accuracy¶
nonlin:accuracy
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¶
nonlin:maxiter
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.
Robberto¶
nonlin:robberto
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¶
cosmicRay:path
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.
Library¶
cosmicRay: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¶
cosmicRay:scale
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
Suffix¶
cosmicRay:suffix
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¶
cosmicRay:seed
Random number generator seed to use when selecting cosmic rays to add.
simSignals section¶
This section of the input file describes how sources and other signals are added to the simulated data.
Point source catalog file¶
simSignals:pointsource
Name of an ascii catalog file listing point sources to add to the simulated image. An example point source catalog is provided on the Catalogs page.
PSF library path¶
simSignals:psfpath
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.
Gridded PSF Library Row Padding¶
The number of outer rows and columns to crop when evaluating the PSF library. This is done to avoid edge effects that can sometimes be present in the evaluated PSF. Recommended and default value is 4.
PSF Wing Threshold File¶
Ascii file that defines the overall size of the PSF (in pixels) versus magnitude. Through this file, the user can tune the size of the PSFs in the
simulated data. If it is important for your science to see far out into the wings, you can enable that here. These files are located in the config
directory of the repo. There is one file per instrument. The default value for this keyword is config. In this case, Mirage will know to look
for the file in the config directory.
Add PSF Wings¶
Boolean value stating whether or not to place the core of the psf from the gridded library into an image of the wings before adding.
PSF library wavefront error¶
simSignals:psfwfe
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¶
simSignals:psfwfegroup
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¶
simSignals:galaxyListFile
Similar to the pointsource entry, this is an ascii catalog file containing a list of the galaxies to simulate in the data. See the galaxies entry on the catalogs page for an example of this file.
Extended source catalog file¶
simSignals:extended
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¶
simSignals:extendedScale
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¶
simSignals:extendedCenter
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¶
simSignals:PSFConvolveExtended
True/False. Convolve the extended image with the appropriate instrumental PSF prior to adding to the output image.
Moving target source catalog file¶
simSignals:movingTargetList
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¶
simSignals:movingTargetSersic
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¶
simSignals:movingTargetExtended
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.
Tracked non-sidereal target catalog file¶
simSignals:movingTargetToTrack
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.
TSO Imaging Catalog¶
simSignals:tso_imaging_catalog
Ascii catalog file containing information on the source to be used when creating imaging TSO observations. The catalog format is detailed in the Imaging TSO Catalog section section of the Source Catalog Formats page.
TSO Grism Catalog¶
simSignals:tso_grism_catalog
Ascii catalog file containing information on the source to be used when creating grism TSO observations. The catalog format is detailed in the Grism TSO Catalog section section of the Source Catalog Formats page.
Zodiacal light¶
simSignals:zodiacal
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.
Tip
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¶
simSignals:zodiscale
Scaling factor to multiply the zodiacal light count rate image by prior to adding to the output data.
Scattered light image¶
simSignals:scattered
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¶
simSignals:scatteredscale
Scaling factor to multiply the scattered light count rate image by prior to adding to the seed image.
Background signal¶
simSignals:bkgdrate
This entry, in combination with the use_dateobs_for_background and date_obs parameters, controls the background signal that is added to simulations. The text below describes the way Mirage interprets the various input options:
Imaging Mode (both NIRCam and NIRISS)
Number: The input value is assumed to be in units of ADU/pixel/second. This constant background value is placed in all pixels.
“low”, “medium”, or “high”. 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.
use_dateobs_for_background set to True: (NOTE: currently the bkgdrate value must be set to “low”, “medium”, or “high” when using this option. If it is set to a number, then that number will be used and use_dateobs_for_background will be ignored.) This is similar to the “low”, “medium”, “high” case above, but instead of calculating the background based on a percetile of the distribution of background values, Mirage will select the background value associated with the date in the date_obs parameter.
WFSS Mode
NIRCam
Number: Not supported
“low”, “medium”, or “high”. Similar to the imaging case above. In this case, the background spectrum matching the percentile value is kept. This is fed into the disperser software, which generates a 2D background image.
use_dateobs_for_background set to True. The background spectrum for the date in the date_obs parameter is fed into the disperser, which generates a 2D background image.
NIRISS
Number: The input number is assumed to be the desired background value in ADU/pixels/second in the undispersed view of the scene. To get the background value in the dispersed image, this number is multiplied by the throughput of the NIRISS grism, which is about 80%. The dispersed background image, which is in the collection of Mirage reference files, is then scaled such that the mean value is equal to the calculated dispersed background value.
“low”, “medium”, or “high”. Same as in the imaging case above. The calculated backrgound value will be multiplied by the throughput of the NIRISS grism, which is about 80%.
use_dateobs_for_background. Not supported
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¶
simSignals:poissonseed
Random number generator seed used for Poisson simulation
Photon Yield¶
simSignals:photonyield
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¶
simSignals:pymethod
This keyword is currently not used. T/F. Whether or not to use the double photon method when applying photon yield.
Expand catalog for segments¶
simSignals:expand_catalog_for_segments
This entry controls whether Mirage will look for a separate point source library for each of the mirror segments on the telescope. This mode is only used for certain wavefront sensing and control observations and should normally be set to False.
Use date_obs for background¶
simSignals:use_dateobs_for_background
This entry controls the way the background signal for the observation is calculated. If it is True, then the background value will be created by extracting the background spectrum assoicated with date_obs from the jwst_backgrounds package. If False, the background will be determined by calculating the background value at a certain percentile of the collection of backgrounds for the given pointing over 365 days. If bkgdrate is “low”, “medium”, “high”, then the percentiles used are 10th, 50th, and 90th, respectively. If it is a float, that value (in ADU/sec/pixel) will be added to all pixels.
Lower Signal Limit for the Segmentation Map¶
simSignals:signal_low_limit_for_segmap
When adding an astrophysical source to the seed image, this is the lower threshold value used to control which pixels in the source are added to the segmentation map. Pixels with signal rates below this threshold will not be included. Mirage uses the segmentation map for WFSS simulations. Only object pixels that are present in the segmentation map are dispersed. This is done, rather than dispersing all pixels, in order to save compute time. The value can be given in a number of units. See signal_low_limit_for_segmap_units below for a list of valid units.
Units for the Lower Signal Limit for the Segmentation Map¶
simSignals:signal_low_limit_for_segmap_units
This field gives the units associated with the value in the :ref: signal_low_limit_for_segmap <signal_low_limit_for_segmap> value above. Supported units include: ADU/sec, ADU/s, e/sec, e/s, MJy/sr, ergs/cm2/a, ergs/cm2/hz. Note that this field is case insensitive. If the signal limit is given in units other than ADU/sec, Mirage will convert the value to ADU/sec before comparing source signal levels and adding pixels to the segmentation map.
Add ghosts¶
simSignals:add_ghosts
If True, Mirage will add optical ghosts to the simulated data. Currently this is only supported for NIRISS F090W, F115W, F140M, F150W, and F200W. In simulations using other instruments or filters, this keyword will be ignored.
Convolve ghosts with PSF¶
simSignals:PSFConvolveGhosts
If True, optical ghosts sources will be convolved with the instrumental PSF before adding them to the simulation
Telescope section¶
Inputs in this section of the yaml file describe the telescope pointing to use for the simulation.
Right Ascension¶
Telescope:ra
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¶
Telescope:dec
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¶
Telescope:rotation
Rotation of the y-axis in degrees East of North. Currently this rotation is defined around the reference location of the chosen subarray.
Telescope tracking¶
Telescope:tracking
Either ‘sidereal’ or ‘non-sidereal’ depending on the type of exposure. If it is set to non-sidereal then the exposure will be created as if JWST is tracking on the source in the movingTargetToTrack catalog. Sources in the pointsource, galaxyListFile, and extended catalogs will trail across the field of view over the course of the exposure.
Output section¶
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.
Output filename¶
Output:file
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.
Output directory¶
Output:directory
The directory into which the output simulated data will be placed.
Data type¶
Output:datatype
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.
Data format¶
Output:format
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¶
Output:save_intermediates
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¶
Output:grism_source_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¶
Output:unsigned
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.
Program number¶
Output:program_number
The proposal ID number. This is placed in the header of the output file in order to match the contents of real observation files.
Proposal title¶
Output:title
The title of the proposal. This placed in the header of the output file in order to match the contents of real observation files.
PI name¶
Output:PI_Name
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¶
Output:proposal_category
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¶
Output:science_category
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.
Target Name¶
Output:target_name
Name of the target. For yaml files constructed from an APT file, this is the name of the target as input by the user. This value will be propagated into the TARGPROP keyword in the simulated data FITS files.
Target RA¶
Output:target_ra
RA of the target. For yaml files constructed from an APT file, this is the RA of the target as input by the user, translated to units of degrees. This value will be propagated into the TARG_RA keyword in the simulated data FITS files.
Target Dec¶
Output:target_dec
Declination of the target. For yaml files constructed from an APT file, this is the declination of the target as input by the user, translated to units of degrees. This value will be propagated into the TARG_DEC keyword in the simulated data FITS files.
Observation number¶
Output:observation_number
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.
Observation label¶
Output:observation_label
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.
Visit number¶
Output:visit_number
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¶
Output:visit_group
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¶
Output:visit_id
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.
Sequence ID¶
Output:sequence_id
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.
Activity ID¶
Output:activity_id
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.
Exposure Number¶
Output:exposure_number
A five-character number used to identify the exposure within the current activity.
Observation ID¶
Output:obs_id
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.
Observation date¶
Output:date_obs
UTC date of the start of the exposure with format yyyy-mm-dd.
Observation time¶
Output:time_obs
UTC time of the start of the exposure with format hh:mm:ss.ssssss.
Observation template¶
Output:obs_template
The name of the observation template used for the exposure (e.g. NIRCam Imaging, NIRCam Time Series)
Primary dither type¶
Output:primary_dither_type
Name of the primary dither pattern in use when the data were obtained. For details, see the documentation pages on dither patterns for NIRCam, and NIRISS. (e.g. INTRAMODULEX, INTRASCA).
Number of primary dither positions¶
Output:total_primary_dither_positions
Total number of primary dither positions in the observation.
Primary dither position¶
Output:primary_dither_position
Primary dither position number of the exposure being simulated.
Subpixel dither type¶
Output:subpix_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¶
Output:total_subpix_dither_positions
Total number of subpixel dither positions for this observation.
Subpixel dither position¶
Output:subpix_dither_position
The subpixel dither position number corresponding to the current exposure.
X offset¶
Output:xoffset
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.
Y offset¶
Output:yoffset
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.