MIRAGE: Multi-Instrument RAmp GEnerator¶
Overview¶
Mirage is a Python package that creates realistic simulated data products for JWST’s NIRCam, NIRISS, and FGS instruments. The output files are in a format that is as close as possible to that which real JWST data will have, which allows Mirage data to be used for data analysis software development and testing, including the official JWST calibration pipeline.
Mirage creates simulated exposures for NIRCam’s imaging and wide field slitless spectroscopy (WFSS) modes, NIRISS’s imaging, WFSS, and aperture masking interferometery (AMI) modes, and FGS’s imaging mode. It supports sidereal as well as non-sidereal tracking (i.e. sources can be made to move across the field of view within an observation).
Astronomical sources to add to the scene are specified through the use of source catalogs.
The software is designed such that a single yaml file can be used as input to create a single simulated exposure from one detector. This file contains various instrument and readout parameters, as well as lists reference files necessary for the production of the simulated data. Details on the contents of the yaml file are given on the Example Yaml page. One yaml file contains all the information necessary to produce a simulated exposure from a single detector.
For software developement and testing, users may wish to simulate all data from a given JWST proposal. In order to do this, Mirage requires one yaml file for each exposure/detector combination. To facilitate this, the Mirage package includes ancillary convenience functions that allow the user to translate an Astronomer’s Proposal Tool (APT) proposal into a series of input yaml files. These tools are described in detail on the Simulating Observations from an APT File page.
Basic Workflow¶
The basic order of steps necessary to produce simulated data with Mirage is:
1. Create the appropriate Source Catalogs. Mirage contains tools to aid in the creation of source catalogs.
2. Create the needed yaml files to descirbe the observations. An easy way to do this is to start with an APT proposal and use Mirage’s yaml file generator tool.
3. Create the simluated data. Run the appropriate module. Most often this will be the imaging simulator or the wfss simulator. To produce only noiseless, background-free countrate images of the scene, the seed image generator module can be used.
See the notebooks in the Mirage repository for basic examples of each of these situations. These include the:
Catalog generation notebook Imaging simulator example notebook WFSS simulator example notebook Moving Target notebook
and for more advanced use:
Commissionning data generation notebook
Under the Hood¶
Broadly speaking, Mirage creates simulated data using three main steps. These include the creation of a noiseless “seed image” of the scene, which contains signal only from astronomical sources. Secondly, a dark current exposure is modified to fit the requested readout pattern. And finally, the seed image and dark current exposures are combined, and noise/cosmic rays are added. See the Three Stages page for details.
Limitations¶
Mirage currently does not simulate coronagraphic observations directly. However the user can input an image of an occulted PSF using the extended source catalog.
When adding PSFs to simulated data, MIRAGE uses the PSFs in the user-provided library. The libraries currently provided in the Mirage reference files collection contain fits files that are 301x301 pixels. This limited size keeps the file sizes small, but cuts off the wings of the PSFs. For very bright sources, the truncated wings will be visible in the data. In addition, when MIRAGE normalizes a PSF to the requested brightness, signal that should be in the truncated wings will instead be in the central 301x301 pixels of the PSF. The total brightness of the source will be as expected, but the signal will be slightly more concentrated in the center of the PSF than it should be.
When creating data for a target that is moving through the field of view, (e.g. a non-sidereal target in a sidereal observation, or vice versa) the velocity of the target is constant. Speed and direction cannot change within an exposure.
Source brightnesses are constant. There is currently no way to simulate a variable brightness source other than by creating multiple exposures of the same source and varying the source brightness from one exposure to the next.
Tangent plane projection is currently not performed when translating from detector pixel x,y values to RA, Dec values. This leads to small errors in the calculated RA, Dec values. This will be corrected in a future version of MIRAGE.
Getting Help
For help installing or running Mirage, or if something is not clear in this documentation, please open an issue on the Mirage github page.
Installing MIRAGE¶
The easiest way to get a working installation of Mirage is to use one of the conda environment files in the repository to create a conda environment. There are two environment files in the package. Use the file that matches your operating system.
- mirage_environment_linux.yml
- mirage_environment_osx.yml
Create a conda environment using the environment file¶
First, be sure that your conda installation is up to date. Exit the current environment if necessary.
conda deactivate
conda update conda
Next, use the appropriate environment file for your operating system to create a new environment.
conda env create -f mirage_environment_osx.yml
Activate the environment¶
conda activate mirage_osx
Install Supporting Packages¶
NIRCam_Gsim – Support for Wide Field Slitless observations
GRISMCONF – Support for Wide Field Slitless observations
For each of these packages, clone or download the repository, cd into the top-level directory, and then install using:
python setup.py install
Reference Files and MIRAGE_DATA Environment Variable¶
In addition to the code itself, there is a set of reference files that accompany Mirage, and are necessary for Mirage to function. These files include dark current ramps, grism throughput curves, cosmic ray and PSF libraries, as well as more standard JWST reference files, such as superbias images, linearity correction coefficients, etc.
Instructions for downloading the reference files are provided on the reference files page.
Reference Files¶
NOTE to users internal to STScI: a collection of Mirage reference files is already present on the STScI network, so there is no need to download them. Please email Bryan Hilbert for the path to use for your MIRAGE_DATA environment variable.
In order to produce data that is as realistic as possible, Mirage is accompanied by a set of reference files that are used to construct the simulated data. After installing Mirage, these reference files can be downloaded using the reference_files module. As the collection of reference files is quite large, users have the option of downloading only certain subsets of the files. For example, if you will only be simulating data from one instrument, you can download only the reference files needed for that instrument. The basic commands to download reference files are shown below.
from mirage.reference_files import downloader
downloader.download_reffiles(download_path, instrument='all', psf_version='subpixel', dark_type='linearized')
The instrument keyword controls which subset of reference files are downloaded. You can give it the name of a single instrument, a string containing a comma-separated list of instruments, or all, which will download reference files for NIRCam, NIRISS, and FGS.
The psf_version keyword controls the PSF libraries that are downloaded. The current version of Mirage uses libraries composed of many PSFs at various sub-pixel locations. These libraries do not include the effects of distortion. Future PSF libraries used by Mirage will be composed of sub-sampled PSFs at various locations across the detector, and will include distortion. In order to download the current PSF libraries, the psf_version keyword should be set to subpixel, or omitted, in which case the script will default to retrieving the current libraries.
The dark_type keyword controls which dark current exposures are downloaded. Mirage requires linearized dark current exposures when creating simulated data. A user may provide raw dark current files, which Mirage will linearize on the fly, or linearized dark current files, which will save processing time. Set this keyword to linearized to download only the linearized versions of the darks, raw to download only the raw versions, or both for both. If omitted by the user, the script will default to downloading only the linearized darks. Note that the darks are by far the largest reference files in the collection (3GB per file, with 5 files per NIRCam detector, 20 for NIRISS, and 8 for FGS) and will take the most time to download.
When called, the function will download the appropriate files from the STScI Box repository, unzip the files, and create the directory structure Mirage expects. It will then remind you to point your MIRAGE_DATA environment variable to the top-level location of these files, so that Mirage knows where to find them.
For example:
export MIRAGE_DATA="/my_files/jwst/simulations/mirage_data"
Reference File Contents¶
There are four main groups of reference files for each instrument: dark current exposures, a PSF library, a cosmic ray library, and a set of reference files used by the JWST calibration pipeline for calibrating data. Note that users are able to run Mirage with alternate reference files. For example, if a specific science case requires larger PSFs, the user can create a new PSF library and replace the downloaded PSF library, or simply update the psf_path entry in their Mirage input yaml files to point to the new library.
Source Catalog File Formats¶
Mirage accepts 7 different types of ascii source catalogs, all of which can be generated using Mirage’s catalog generation functionality. These include:
- Point sources
- Galaxies (2d Sersic profiles)
- Extended targets
- Non-sidereal source
- Moving point sources
- Moving Sersic sources
- Moving extended sources
Tip
For information on the optional hdf5 catalog that can be used when simulating WFSS data, see the WFSS simulation page.
The type of source catalog(s) you need depends on the scene you are simulating. The table below shows the possible catalogs for sidereal and non-sidereal observations. For sidereal observations, the point source, galaxy, and extended source catalogs can be used to create static sources in the scene. The three types of moving target catalogs can be used to create sources that trail across the field of view during the observation. For non-sidereal observations, the non-sidereal source catalog is used to create a static source in the scene. This is the non-sidereal target which JWST is tracking. The other types of catalogs can then all be used to create trailed sources. In this case, the inverse of the non-sidereal source’s velocity is applied to all targets in the other catalogs. In this way, Mirage will create trailed background stars and galaxies, as well as trailed non-sidereal targets that have velocities other than that of the main target.
| Type of observation | Static source catalogs | Trailed (moving) source catalogs |
|---|---|---|
| Sidereal |
|
|
| Non-sidereal |
|
|
Common formatting details¶
Mirage scans the top 4 lines of each catalog for certain phrases that can be used to characterize the inputs. These phrases are used to specify the units of source locations or velocities, as well as the magnitude system to use. Multiple phrases can be used in a single catalog, but only one phrase per line is allowed. Examples are shown in the catalogs below.
The locations of sources can be specified in RA, Dec or in (x,y) pixel locations on the detector. If you wish to provide positions in units of (x, y) detector pixels, then the string ‘position_pixels’ must be added after the # in one of the top 4 lines of the file.
Tip
RA and Dec values can be given in decimal degrees, colon-separated values (HH:MM:SS and DD:MM:SS), or in more conventional string formats, but all sources in a given catalog must have the same format:
53.08864 -27.83999
03:32:21.273 -27:50:23.983
03h32m21.273s -27d50m23.983s
Mirage uses AB magnitudes as the default for input sources. However, you can change the magnitude system by specifying an alternative in one of the top 4 lines. The three acceptible options are vegamag, stmag, and abmag. All sources in a given catalog must be in the same magnitude system.
For moving targets (both those that are moving across the field of view, as well as non-sidereal targets), the default unit for velocity is arcseconds per hour. If you wish to instead use pixels per hour, then velocity_pixels must be added to one of the 4 top lines of the catalog.
Point Sources¶
Point sources are specified using a catalog that includes the locations of the sources in RA and Dec (or x,y pixel locations on the detector) and the corresponding magnitudes through the filter specified by the user. Currently the simulator supports the use of ABMAG [Oke, 1983]_, STMAG [Stone, 1996]_ , and VEGAMAG () systems, with ABMAG as the default.
An example point source catalog is shown below with the positions given in RA and Dec.
#
#
#
# abmag
#
# Magnitudes are converted from input flux densities.
x_or_RA y_or_Dec nircam_f200w_magnitude
53.0886395 -27.8399952 20.0
53.0985009 -27.8398137 19.2
Mirage looks for the exact column names shown above when reading point source catalogs. Changing these column names will cause the simulator to fail when attempting to read in the file.
Galaxies (aka 2D Sersic profiles)¶
Below is an example of a galaxy source catalog. In this case, galaxy positions are given in RA, Dec decimal degrees, and the half light radii are in units of arcseconds. The half light radius can also be specified in units of pixels. In that case, you must add radius_pixels after the # in one of the top four lines.
Position angle values are defined as degrees east of north.
The simulator software looks for the exact column names shown below when reading these catalogs. Changing these column names will cause the simulator to fail when attempting to read in the file.
#
#
#
# abmag
#
# Magnitudes are converted from input flux densities.
x_or_RA y_or_Dec radius ellipticity pos_angle sersic_index niriss_f200w_magnitude
53.05 -27.83 0.17 0.46 104.35 3.3 18.06
53.10 -27.83 0.73 0.01 195.50 2.7 16.86
Extended Objects¶
The extended object catalog lists files containing stamp images to be added to the seed image. For example, a source such as a nebula or spiral galaxy that cannot be simulated via a 2-dimensional Sersic profile can be added by placing an image of the source in a fits file. Mirage will then read in, scale, and add this image to the seed image.
It is assumed that the fits file contains an array in the 1st (rather than 0th) extension. The array can be any size. If it is larger than the field of view of the simulated data, then it is cropped by placing the center of the extended stamp image at the specified x,y or RA, Dec location on the detector, and cropping any areas that fall outside of the detector.
Each row of this catalog contains the name of a FITS file containing the image to use, along with the RA, Dec (or x,y) position of the source, the position angle to use, and the source’s magnitude. The position angle is the angle in degrees counter clockwise to rotate the as-read-in image before adding it to the simulated scene. For stamp images where it may not make sense to specify a magnitude (such as a galaxy cluster), it is possible to specify ‘None’ as the magnitude. In this case the code assumes that the data contained in the fits file is in units of ADU per second, and will not rescale the data before adding to the seed image. However, the user can also adjust the signal rate of all extended sources through the use of the extendedScale field in the input yaml file. This is a multiplicative factor to apply to the data in the fits file prior to adding the source to the seed image.
#
#
#
#
# Columns 1 and 2 can be either x,y positions on the detector aperture (e.g.
# 0,0 is lower left corner of the full frame of the subarray used for the
# output) or RA,Dec location of the center of the source. If they are x,y
# positions, make the top line of the file '# position_pixel'
#
#
#
x_or_RA y_or_Dec pos_angle nircam_f200w_magnitude filename
359.65 0.0006 20 16.000 ring_nebula.fits
Non-sidereal Source¶
This catalog is used when creating non-sidereal simulated exposures. In this case, all targets other than the non-sidereal target will then trail through the field of view during the observation. This mode is meant to simulate observations of solar system targets with non-sidereal velocities. This catalog should contain only one entry, with RA, Dec or x, y position, as well as velocity values (arcsec/hour or pixels/hour) and object magnitude.
#
#
#
# abmag
#
# radius can also be in units of pixels or arcseconds. Put 'radius_pixels' at top of file
# to specify radii in pixels.
# position angle is given in degrees counterclockwise.
# An "object" value containing 'point' will be interpreted as a point source.
# Anything containing "sersic" will create a 2D sersic profile.
# Any other value will be interpreted as an extended source.
# x_or_RA_velocity is the proper motion of the target in units of arcsec (or pixels) per hour
# Y_or_Dec_velocity is the proper motion of the target in units of arcsec (or pixels) per hour
# if the units are pixels per hour, include 'velocity pixels' in line 2 above.
object x_or_RA y_or_Dec x_or_RA_velocity y_or_Dec_velocity nircam_f200w_magnitude
pointSource 53.101 -27.801 2103840. 0.0 17.
Moving Point Sources¶
The moving point source catalog contains a list of point sources to move through the field of view during the integration. Similar to the static point source catalog, the position of each object (at the beginning of the integration) in RA, Dec or x,y must be provided, along with the object’s magnitude in the filter used for the simulation. In addition, the velocity of the object must be specified. This is done in units of delta RA, delta Dec (arcsec/hour), or delta x, delta y (pixels/hour). ‘velocity_pixels’ must be placed in one of the top 4 lines of the file if the provided velocities are in units of pixels per hour rather than arcseconds per hour.
Below is an example catalog:
#
#abmag
#
#
# List of point sources to create as moving targets (KBOs, asteroids, etc)
# position can be x,y or RA,Dec. If x,y, put the phrase 'position_pixels' in one
# of the top 4 lines of the file.
# Velocity can be in units of pix/hour or arcsec/hour.
# If using pix/hour, place 'velocity_pixels' in the second line of the file.
# Note that if using velocities of pix/hour, the results will not be
# strictly correct because in reality distortion will cause object's
# velocities to vary in pixels/hour. Velocities in arcsec/hour will be
# constant.
x_or_RA y_or_Dec nircam_f200w_magnitude x_or_RA_velocity y_or_Dec_velocity
53.0985 -27.8015 14 180 180
Moving 2D Sersic Objects¶
This option may be useful for simulating moving moons around a primary target that is being tracked. Similar to the static galaxy inputs, each moving target in this catalog must have an initial position in RA, Dec or x,y specified, along with a radius in arcseconds or pixels, ellipticity, position angle, Sersic index, and magnitude. In addition, velocities in the RA, Dec or x,y directions must be specified in units of arcseconds or pixels per hour.
#
#
#
#abmag
# Columns 1 and 2 can be either x,y positions on the detector aperture (e.g.
# 0,0 is lower left corner of the full frame of the subarray used for the
# output) or RA,Dec location of the center of the source. If they are x,y
# positions, make the top line of the file '# position_pixels'
#
# radius is the half-light radius in pixels or arcseconds. If in pixels
# make the second line of the file '# radius_pixels
#
# pos_angle is the position angle of the semimajor axis, in degrees.
# 0 causes the semi-major axis to be horizontal.
x_or_RA y_or_Dec radius ellipticity pos_angle sersic_index nircam_f200w_magnitude x_or_RA_velocity y_or_Dec_velocity
354.765 0.00064 1.0 0.25 20 2.0 16.000 -0.5 -0.02
Moving Extended Sources¶
Similar to the catalog of static extended targets, this catalog contains a fits filename for each source containing the stamp image to use for the object, along with an initial position in RA, Dec or x,y, the object’s magnitude, and position angle (of the array as read in from the fits file). In addition, velocities in the RA, Dec (arcsec/hour) or x,y directions (pixels/hour) must be specified.
#
#
#
#abmag
# List of stamp image files to read in and use to create moving targets.
# This is the method to use in order to create moving targets of
# extended sources, like planets, moons, etc.
# position can be x,y or RA,Dec. Velocity can be in units of pix/hour or arcsec/hour.
# If using pix/hour, place 'velocity_pixels' in one of the top 4 lines.
# Note that if using velocities of pix/hour, the results will not be
# strictly correct because in reality distortion will cause object's
# velocities to vary in pixels/sec. Velocities in arcsec/hour will be
# constant.
filename x_or_RA y_or_Dec nircam_f200w_magnitude pos_angle x_or_RA_velocity y_or_Dec_velocity
ring_nebula.fits 0.007 0.003 12.0 0.0 -0.5 -0.02
Tools for Creating Source Catalogs¶
To help users create source catalogs in the proper format, Mirage contains the catalog generator and create catalog modules. catalog_generator.py contains classes for each of the types of catalogs accepted by Mirage. The create_catalog.py module contains functions that will query several astronomical databases and attempt to construct realistic point source and extragalactic catalogs for a given pointing. There is also a function for automated catalog creation from an input APT file. See the Catalog Generation Tools notebook in the Mirage repository for examples of all of this functionality.
Catalog_generator - Create catalogs from a list of sources¶
The classes in this module can be used to simplify Mirage catalog creation from lists of source coordinates and magnitudes. Generally the user instantiates the class for the desired type of catalog with a list of RA and Dec or detector x, y source positions. Magnitude columns can then be added to the catalog by providing a list of magnitudes as well as the instrument and filter name associated with the magnitudes. Catalogs may contain multiple magnitude columns covering multiple instruments and filters. Examples of how to use the catalog generator functionality are given in the Catalog Generation Tools notebook notebook. Below, we show examples for the most common catalogs: point sources and galaxies.
Point Source Catalog¶
The examples below create point source catalogs containing 10 sources. By supplying source locations via the ra and dec keywords, Mirage assumes that the locations are Right Ascention and Declination values given in decimal degrees. If you wish to specify source locations in units of row and column indexes on the detector, then the x and y keywords should be used, as seen in the second example below.
Columns containing AB magnitudes in the NIRCam F200W and F212N filters, as well as the NIRISS F090W filter are added to the catalog using the add_magnitude_column method. Note that the instrument and filter names associated with the magnitude values must be supplied in these calls. The mag_sys keyword is optional and allows uses to specify the magnitude system. Allowed values are “abmag”, “stmag”, and “vegamag”. The default is “abmag”. Note that all magnitude columns in a given catalog MUST be in the same magnitude system.
Once the catalog has been created and at least one magnitude column has been added, the table can be printed to the screen using the table method.
The save method will save the table in an ascii file in the appropriate format for Mirage to use.
import numpy as np
from mirage.catalogs import catalog_generator
ra_list = np.random.random(10) + 53.5
dec_list = np.random.random(10) - 67.2
nrc_f200w_mag = np.random.random(10) + 16.
nrc_f212n_mag = np.random.random(10) + 19.
nis_f090w_mag = np.random.random(10) + 15.5
ptsrc = catalog_generator.PointSourceCatalog(ra=ra_list, dec=dec_list)
ptsrc.add_magnitude_column(nrc_f200w_mag, instrument='nircam', filter='F200W', mag_sys='abmag')
ptsrc.add_magnitude_column(nrc_f212n_mag, instrument='nircam', filter='F212N', mag_sys='abmag')
ptsrc.add_magnitude_column(nis_f090w_mag, instrument='niriss', filter='F090W', mag_sys='abmag')
ptsrc.save('point_sources.cat')
ptsrc.table()
x_list = np.random.random(10) * 2048
y_list = np.random.random(10) * 2048
ptsrc = catalog_generator.PointSourceCatalog(x=x_list, y=y_list)
ptsrc.add_magnitude_column(nrc_f200w_mag, instrument='nircam', filter='F200W', mag_sys='abmag')
ptsrc.add_magnitude_column(nrc_f212n_mag, instrument='nircam', filter='F212N', mag_sys='abmag')
ptsrc.add_magnitude_column(nis_f090w_mag, instrument='niriss', filter='F090W', mag_sys='abmag')
ptsrc.save('point_sources_xy.cat')
Galaxy Catalog¶
The example below creates a galaxy catalog. The main difference compared to the point source catalog is that the user must provide values for the ellipticity, sersic index, and position angle when instantiating the class.
import numpy as np
from mirage.catalogs import catalog_generator
ra_list = np.random.random(10) + 53.5
dec_list = np.random.random(10) - 67.2
ellipticity = np.random.random(10) * 0.75
sersic_index = np.random.random(10) * 4.
position_angle = np.random.random(10) * 359.
nrc_f200w_mag = np.random.random(10) + 16.
nrc_f212n_mag = np.random.random(10) + 19.
nis_f090w_mag = np.random.random(10) + 15.5
gal = catalog_generator.GalaxyCatalog(ra=ra_list, dec=dec_list, ellipticity=ellipticity,
sersic_index=sersic_index, position_angle=position_angle)
gal.add_magnitude_column(nrc_f200w_mag, instrument='nircam', filter='F200W', mag_sys='abmag')
gal.add_magnitude_column(nrc_f212n_mag, instrument='nircam', filter='F212N', mag_sys='abmag')
gal.add_magnitude_column(nis_f090w_mag, instrument='niriss', filter='F090W', mag_sys='abmag')
gal.save('galaxies.cat')
gal.table()
Create_catalogs - create catalogs using online astronomical databases¶
The functions in this module use astroquery to search astronomical databases and retrieve source lists for a given pointing. In this way, a user can quickly generate reasonably realistic catalogs of point sources and galaxies for a given pointing.
The get_all_catalogs function takes the RA and Dec of a particular pointing along with the width in arcseconds of the area for which to produce the catalog, and queries multiple databases to produce a point source catalog. An example call to create a 120 x 120 arcsecond catalog is shown below. The resulting point source catalog can then be placed in the pointSource entry of the yaml input file. Note that an email address is required input for the Besancon model query.
from mirage.catalogs import create_catalogs
ra = 80.4 # degrees
dec = -69.8 # degrees
box_width = 120 # arcseconds
filter_list = ['F444W', 'F480M']
cat, mag_column_names = create_catalog.get_all_catalogs(ra, dec, box_width, kmag_limits=(13, 29),
instrument='NIRCAM', filters=filter_list,
email='someone@somewhere.edu')
Foreground Stars¶
A realistic list of foreground stars is compiled by querying the 2MASS, WISE, and GAIA catalogs using the given pointing. Using the retrieved magnitudes in the various bands associated with these surveys, Mirage converts these to magnitude values in the requested NIRCam or NIRISS filters. Note that these queries return stars only down to about V=16. For dimmer stars, Mirage queries the Besancon model. This process is described in the Background Stars section below. The code needed to produce the foreground and background star lists, and combine the two into a single catalog is also shown in the Bakcground Stars section below.
Background Stars¶
To obtain a list of stars dimmer than those returned in the Foreground Stars search, Mirage uses astroquery to query the Besancon model of stars in the Milky Way. This query returns a representative sample (in terms of luminosity distribution) of stars for a given pointing, including a realistic stellar density and realistic luminosity distribution. Note that these stars are not actual stars in the sky.
Background Galaxies¶
For a given pointing, Mirage can also generate a catalog containing a representative sample of background galaxies. Similar to the Besancon query described above, Mirage will generate a catalog containing a realistic density of galaxies across the field at reasonable magnitudes. To accomplish this, Mirage queries the GOODS-S catalog from 3DHST and extracts an appropriate number of galaxies to populate the catalog at a reasonable density. Currently this function will fail if the user requests a catalog with an area larger than the GOODS-S field: 606,909 arcsec 2. An example is shown below. The resulting file can then be placed in the galaxyListFile entry of the yaml input file.
Mirage’s Three Stages¶
Mirage can be broadly divided into three stages. Mirage first creates an idealized, noiseless image of the astronomical scene. We refer to this as the “seed image”. It then reorganizes an existing dark current exposure to match the characteristics of the specified simulation. The seed image and the dark current exposure are then combined.
Below is a more detailed flow chart showing Mirage’s overall process for creating simulated data. Blue boxes show user inputs, and white boxes contain outputs.
Seed Images¶
The first stage is the creation of the “seed image”. This is a noiseless count rate image that contains signal only from the astronomical sources to be simulated. Seed images include instrument distortion effects, so that given RA, Dec values are properly converted to pixel x,y values, with the exception of tangent plane projection, which will be added soon. Mirage currently contains two methods for the construction of seed images:
- Through the use of source catalog files
- Extraction from a fits file containing a distortion-free image (e.g. HUDF, GOODS, CANDELS, etc)
For WFSS observations, multiple seed images or optional input spectra are then fed into the disperser software, which simulates the effects of the grism by dispersing the signal from the astronomical sources, creating a “grism seed image”.
For a detailed description of seed image creation, see the Seed Images page.
Dark Current Preparation¶
The second stage is the preparation of the dark current exposure to use for the simulation. The input dark current exposure is reorganized into the requested readout pattern and number of groups and cropped to the requested subarray size. Detector non-linearity effects are then removed using the initial steps of the JWST calibration pipeline.
By using actual dark current exposures from ground testing, Mirage is able to capture many effects which are specific to the instrument and detector being simulated. For example, the 1/f noise, bias structure, and hot pixel population.
Details of the dark current preparation are given on the Dark Preparation page.
Observation Generation¶
The final stage involves the combination of the seed image and the dark current in order to produce the output exposure. The seed image is expanded into integrations with groups that follow the requested readout pattern. Other effects are also added at this stage, including cosmic rays, interpixel capacitance (IPC) and crosstalk effects.
More details are provided on the Observation Generation page.
Creation of Seed Images¶
A “seed image” is a noiseless image that contains signal only from simulated astronomical sources, created during the first stage of Mirage. In addition to containing no noise, there are no cosmic rays nor dark current. The seed image can be used as a “truth image” for the purposes of quality checks on the final output data.
Mirage generates seed images in one of two ways:
- From source catalogs
- Extraction from a fits file containing a distortion-free image (e.g. HUDF, GOODS, CANDELS, etc)
Seed images from source catalogs¶
To create a seed image from user-specified source catalogs, the catalog_seed_image.py module is used. There are two types of observations supported by this method, sidereal and non-sidereal, and several catalogs to go with each. The Catalogs page shows examples of each type of source catalog that can be used by Mirage.
For each type of target, Mirage creates or retrieves a small stamp image of the target based on the user-supplied parameters in the catalog. This stamp image is then placed into the seed image at the x,y or RA, Dec location specified by the user. Source locations on the detector take into account instrument distortion. If source locations in the catalogs are specified using RA and Dec, Mirage will use the distortion model from a distortion reference file if supplied in the input yaml file. If no reference file is given, Mirage will fall back to using distortion information in the Science Instrument Aperture File (SIAF).
For point sources, Mirage selects the appropriate PSF for each source from a PSF library. This PSF is scaled to the requested brightness, and then placed in the correct location on the detector.
Galaxies in Mirage are represented by 2 dimensional Seric profiles. These are created using astropy’s Sersic2D model, scaled to the requested brightness, and placed in the seed image.
“External sources” is the term used for stamp images that are read in from supplied fits files. In this case, the user-suppied fits file is read in and the image is scaled and placed in the seed image at the requested location. See the Catalogs page for more details.
After simulated astronomical sources are added to the seed image, background signals can be added using the bkgrnd entry in the input yaml file. Users can request a constant background in units of ADU/pixel/second, or a general background level. For the latter, Mirage uses the jwst_backgrounds package to add zodiacal and thermal background signal. In this case, “low”, “medium”, or “high” are the three values that can be used. The definition of these terms mirrors those used in APT and the JWST ETC.
For a given pointing, jwst_backgrounds will calculate the total expected background level (zodiacal plus thermal) for each day over the course of a year. A “low” background is defined as the background level corresponding to the 10th percentile of this distribution of background levels. “Medium” is 50th percentile, and “high” is 90th percentile.
Users can also provide a custom background through the use of an input fits file referenced in the “zodiacal” entry of the input yaml file. In this case, the contents of the file are read in and added to the seed image.
Finally, Mirage uses the pixel area map to mimic the effects of distortion on the simulated sources. While the locations of the simulated sources within the seed image accurately account for distortion, the brightness of the sources are not affected. The seed image (minus any point sources) is multiplied by the pixel area map in order to adjust the extended sources’ brightness to account for the relative differences in pixel areas across the detector.
Seed images from distortion-free images¶
Another way to create a seed image is through the use of a large field-of-view image from a FITS file. This file should contain a north-up, distortion-free count rate image at an arbitrary pixel scale with a proper world coordinate system (WCS) in the header.
In this case, the portion of the image corresponding to the requested RA, Dec of the simulation is extracted from the input, and some of the JWST calibration pipeline functionality is used to resample it onto the appropriate JWST instrument pixel grid while also introducing the appropriate distortion for the requested detector. This functionality is a new implementation of Astrodrizzle’s blotting function, and works in essentially the same way. For more details on Astrodrizzle, see the DrizzlePac website. The simulator then saves this blotted image in the seed image format used by subsequent steps of MIRAGE.
In order to create a seed image from this input file, the simulator uses the fits_seed_image.py, function. For convenience, this function accepts the same yaml input file as the other parts of the simulator. Alternatively, the user has the option of manually specifying the necessary parameters. Below we show an example of how to create a seed image from an input mosaic file using either a yaml file or by setting parameters manually.
from mirage.scripts import fits_seed_image
# Two input options:
# 1. a yaml file matching that used by the MIRAGE
s = fits_seed_image.ImgSeed('fits_seed_image_test.yaml')
s.mosaicfile = 'my_mosaic_drz.fits'
s.crop_and_blot()
#2. set the parameters manually
s = fits_seed_image.ImgSeed()
s.mosaicfile = 'my_mosaic_drz.fits'
s.aperture = 'NRCB5_FULL'
s.crop_center_ra = 53.1
s.crop_center_dec = -27.8
s.blot_center_ra = 53.1
s.blot_center_de = -27.8
s.blot_pav3 = 0.
s.subarray_defs = 'config'
s.flux_cal_file = 'config'
s.filter = 'F250M'
s.pupil = 'CLEAR'
s.grism_source_image = False
s.outfile = 'test_mosaic_seed.fits'
s.outdir = './'
s.crop_and_blot()
Preparation of the Dark Current Exposure¶
After creating the seed image mirage moves on to preparing the input dark current exposure. This involves manipulating the input dark current exposure in several ways.
Adjust Number of Frames/Groups and Integrations¶
Frist the number of groups and integrations are adjusted to match the requested groups and integrations specified in the input yaml file. If the input dark has more groups or integrations than the requested output, the extras are removed. If additional groups or integrations are required above what is present in the dark file, then copies of existing groups/integrations are made and appended to the observation. In the case where extra groups are needed, copies of the existing groups are added to the signal in the final group of the existing dark, such that the dark current signals continue increasing in as they would in a longer integration.
Put into Requested Readout Pattern¶
Next, the readout pattern of the dark current exposure is adjusted to match the requested output. Effectively this only works in two cases. If the input dark and output exposure have the same readout pattern, then no action is taken. If the input dark is in the RAPID or NISRAPID (for NIRCam and NIRISS respectively) readout mode, where each group is composed of only one frame, then frames can be averaged/dropped in such a way to transform the dark into any other readout pattern. Input darks using readout patterns other than RAPID/NISRAPID cannot be translated into any other readout patterns, as all other readout patterns have groups composed of averaged frames, such that the original information from all frames is not accessible.
Calibration and Linearization¶
If the input dark current exposure is “raw”, meaning that no calibration steps have been performed on the data, then the reorganized dark is run through the superbias and reference pixel subtraction, as well as the non-linearity correction steps of the JWST calibration pipeline. The signal subtracted in the superbias and reference pixel subtraction steps is saved. Once the simulated data are created, this signal can be added back in order to create a “raw” exposure if requested.
There is also an option to provide a linearized, rather than raw, dark current exposure. In this case, the file containing the linearized dark current also must contain the subtracted superbias and reference pixel signal, and the pipeline steps are subsequently skipped. ]
Crop to Requested Subarray¶
Once the linearized dark current exposure is present, it is then optionally cut down to the requested subarray size. At this point, the dark current data are ready to have signals from simulated sources added.
Tip
Both raw and linearized dark current exposures are provided in the collection of reference files that accompany mirage.
Generate Observation¶
The final stage of the simulator is the observation generator. Here, the seed image is combined with the dark current exposure to create the final simulated data. This process includes several steps: addition of instrumental effects to the seed image, translation of the seed image from a count rate image to a signal ramp, the addition of noise sources, and finally summing the simulated signals with the dark current signals.
Translate Seed Image into a RAPID Exposure¶
The first task performed in the observation generator is to translate the seed image, which is a count rate image, into a “seed exposure” composed of multiple frames with signals in counts. Specifically, the seed image is translated into one or more integrations using the RAPID, NISRAPID, or FGSRAPID readout pattern. The exposure is the collection of these integrations.
Add Cosmic Rays¶
Cosmic rays are then added to the seed exposure. Cosmic ray details are controlled through the entries in the cosmicRay section of the input yaml file. The user must provide a pointer to the location of the cosmic ray library. The cosmic ray libraries that are included in Mirage’s reference files are based on the cosmic ray library created by Massimo Robberto, which is detailed in his 2009 technical report.
Three separate cosmic ray libraries are provided in the reference file collection. These libraries are accessed using the cosmicRay:library yaml file entry. The three options are SUNMIN, SUNMAX, and FLARE. Each library has an associated cosmic ray rate, shown below. Users can modify these rates through the multiplicative factor specified in the cosmicRay:scale entry.
Default cosmic ray rates (cosmic rays / pixel / second):
| SUNMIN |
|
| SUNMAX |
|
| FLARE |
|
Add Poisson Noise¶
Mirage then adds Poisson noise to the seed exposure. This is done one frame at a time within the integration, with the signal for each frame dependent upon the signal and poisson noise from the previous frame. Through the simSignals:poissonseed entry in the input yaml file, users can provide a seed to the random number generator used to create the Poisson noise, in order to have reproducible results.
Flat Field Effects¶
If the user provides an illumination flat or pixel flat in the Reffiles:illumflat or Reffiles:pixelflat yaml file entries, these files are read in and multiplied into the seed exposure.
IPC¶
Interpixel capacitance (IPC) effects are added to the seed exposure at this point. IPC is an electronic coupling between adjacent pixels that causes some of the signal generated in a pixel to be measured by a neighboring pixel (Donlon 2016). To add IPC, we convolve the image with a user-specified IPC kernel. Typically the kernel is a 3x3 array. The kernel lists the relative fraction of signal that will be measured in the 3x3 grid of pixels around a central pixel that sees some input flux. For example, in the case where 0.5% of the signal spreads to each of the 4 pixels immediately adjacent to the central pixel, we would use the kernel shown below.
| 0.0002 | 0.0050 | 0.0002 |
| 0.0050 | 0.9792 | 0.0050 |
| 0.0002 | 0.0050 | 0.0002 |
This is the inverse of the kernel that can be used by the JWST calibration pipeline to remove IPC effects, like that shown below. Therefore, Mirage has an option to accept a pipeline-formatted kernel that will then be inverted before being used to add IPC effects. It is also possible to use a file with a separate 3x3 kernel for each pixel. In this case the total kernel will have a shape of 2048 x 2048 x 3 x 3.
| -0.0002 | -0.0052 | -0.0002 |
| -0.0052 | 1.0214 | -0.0052 |
| -0.0002 | -0.0052 | -0.0002 |
The latest IPC kernels for all instruments and detectors are provided in the reference files assocaited with Mirage.
Add Seed Exposure to Dark Current Exposure¶
At this point, the seed exposure is added to the dark current exposure from the previous stage. At this point, both are in the RAPID, NISRAPID, or FGSRAPID readout pattern, depending on instrument. They are added frame by frame, resulting in a single observation exposure.
Crosstalk¶
Crosstalk effects can also be added to the observation. Crosstalk in this case is defined as the unintentional mirroring of a fraction of the measured signal across amplifiers. Bright sources located in one quadrant of a detector can create dimmed copies of themselves in the other three quadrants. Crosstalk on the NIRCam detectors has been quantified by Armin Rest. Results are detailed in his 2015 technical report. Crosstalk is added to the observation using an input file containing crosstalk coefficients. These coefficients control the magnitude and sign of the crosstalk signal between each combination of amplifiers. Currently, only the NIRCam detectors have non-zero crosstalk coefficients in the collection of Mirage reference files.
(Optionally) Return from Linearized to Raw State¶
At this point, the observation contains linearized, partially calibrated (superbias and reference pixel subtracted) signal. This can be directly saved to an output fits file in the format used by the JWST calibration pipeline. There is also an option to return the observation exposure to a completely uncalibrated (“raw”) state, such that the full calibration pipeline can be run on the data. The advantage of this is that pipeline parameters and settings can be customized/optimized by the user.
In order to return to a raw state, the linearization step of the pipeline is run in reverse on the data. The previously subtracted superbias and reference pixel signal is then added back in to the exposure.
Save Observation¶
With the construction of the observation exposure complete, the exposure is then saved in the requested format.
Hint
The output format of the data is controlled by the Output:datatype line in the input yaml file. Possible values for this parameter include “raw”, “linear”, or “raw,linear”. In the latter case, both the linearized and raw versions of the observation will be saved.
Simulating Observations from an APT File¶
The easiest way to simulate a large amount of obsrvtions using Mirage is to begin with the APT file of a JWST proposal. Mirage contains functions that can (for imaging and WFSS modes) create the collection of yaml files necessary to simulate all of the observations contained in the APT file.
Examples of this functionality are shown in the notebooks in the Mirage repository. Below are step-by-step instructions explaining how to create Mirage input yaml files from an APT file.
Export XML and Pointing files from APT¶
Open the proposal within APT and under the File menu, choose Export, and select the xml and pointing files. Only one file at a time can be exported, so the process must be repeated for each.
Additional Yaml Generator Inputs¶
In addition to the xml and pointing files, there are several user-inputs needed by the yaml generator.
Source catalogs¶
The user must specify source catalogs for each instrument and observation. This is done using a nested dictionary following the form shown below. Catalogs for NIRCam are broken down by channel (SW, LW). In each case, the entry can be a list of catalogs, in which case there must be one catalog in the list for each observation in the program that uses the instrument. For example, in an APT file containing 5 observations, if NIRCam is used in observations 1, 2, and 4, and NIRISS in observations 3 and 5, then the NIRCam catalog lists should have a list of three catalogs, and the NIRISS entry should have a list of 2 catalogs. The code assumes that the catalogs are listed in the same order of the observations in the APT file.
Alternatively, the user may provide a string containing a single catalog name, rather than a list. In this case, Mirage assumes that the same catalog will be used in all observations.
catalogs = {'nircam': {'sw': {ptsrc: [list of catalogs], 'galaxy': [list of catalogs]}
'lw' : {ptsrc: [list of catalogs], 'galaxy': [list of catalogs]}
'niriss': {'ptsrc': [list of catalogs], 'galaxy': [list of catalogs]}
}
Note that currently this format is used for point source catalogs only. Other types of catalogs are limited to a single entry in a separate parameter dictionary as shown in the Other Paramteres section. Catalog entries will be made more consistent in a future update. In the meantime, the easiest way to get the proper (non-point-source) catalogs into the yaml files is to use a single catalog for all observations and instruments. This is easily done by adding all necessary magnitude columns into a single catalog, or by combining existing Mirage catalogs. See the Catalog Generation notebook for examples.
Other Parameters¶
There are currently a number of parameters which can only be set using the parameter_defaults keyword in the yaml_generator. These parameters are currently limited in that only a single value is accepted for each, and applied to all observations in a proposal. An update to allow different values to different observations will be made soon. For the moment, the list of parameters that can be set with this method are shown below. The values are the defaults used by Mirage if the user does not enter their own values.
param_values['Date'] = '2019-07-04'
param_values['PAV3'] = '111.'
param_values['GalaxyCatalog'] = 'None'
param_values['ExtendedCatalog'] = 'None'
param_values['ExtendedScale'] = '1.0'
param_values['ExtendedCenter'] = '1024,1024'
param_values['MovingTargetList'] = 'None'
param_values['MovingTargetSersic'] = 'None'
param_values['MovingTargetExtended'] = 'None'
param_values['MovingTargetConvolveExtended'] = 'True'
param_values['MovingTargetToTrack'] = 'None'
param_values['BackgroundRate_sw'] = 'low'
param_values['BackgroundRate_lw'] = 'low'
param_values['BackgroundRate'] = '0.5'
Run the Yaml Generator¶
With the XML and pointing files in hand, and additional inputs defined above, Mirage’s yaml_generator.py module can be called to create the associated yaml files. We specify a location for the oputput yaml files using the output_dir keyword. We also define the directory into which the final simulated data will be placed, using the simulated_output_dir keyword. This information will be placed into the constructed yaml files.
Setting the use_linearized_darks option to True will cause the yaml_generator to look for linearized dark current files to use with the simulations. These files may be present in the collection of Mirage reference files. If linearized darks are not present, leaving this option as False will cause Mirage to use raw dark current ramps as inputs.
Note that the point source catalogs and other parameters described above are inputs as well.
from mirage.yaml import yaml_generator
yam = yaml_generator.SimInput(xml_file, pointing_file, catalogs=catalogs, verbose=True,
output_dir='/location/to/place/yaml_files',
simdata_output_dir='/location/to/place/simulated_data',
parameter_defaults=param_values, datatype='raw')
yam.use_linearized_darks = True
yam.create_inputs()
The outptut from this will be the collection of yaml files needed to run Mirage and create all of the simulated observation files. An example yaml file shows all of the parameters necessary when simulating an exposure.
See the Imaging and WFSS notebooks in the Mirage repository for examples of yaml_generator use.
Run Mirage¶
The collection of yaml files can then be fed into Mirage one at a time.
from glob import glob
from mirage import imaging_simulator
yaml_files = glob('*.yaml')
for yfile in yaml_files:
im = imaging_simulator.ImgSim()
im.paramfile = yfile
im.create()
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)
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.
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
The collection of reference files associated with Mirage contains a library of bad pixel masks that can be used.
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
The collection of reference files associated with Mirage contains a library of superbias files that can be used.
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
The collection of reference files associated with Mirage contains a library of linearity coefficient files that can be used.
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
The collection of reference files associated with Mirage contains a library of saturation map files that can be used.
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
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¶
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
The collection of reference files associated with Mirage contains a library of distortion reference files that can be used.
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
The collection of reference files associated with Mirage contains a library of IPC kernel files that can be used.
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.
Pixel area map¶
Reffiles:pixelAreaMap
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.
Hint
The collection of reference files associated with Mirage contains a library of pixel area map files that can be used.
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
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
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.
PSF library file basename¶
simSignals:psfbasename
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¶
simSignals:psfpixfrac
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¶
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.
Convolve moving extended targets with PSF¶
simSignals:movingTargetConvolveExtended
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¶
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.
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:scatteredscake
Scaling factor to multiply the scattered light count rate image by prior to adding to the seed image.
Background signal¶
simSignals:bkgdrate
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¶
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.
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.
newRamp section¶
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.
Hint
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¶
newRamp:dq_configfile
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¶
newRamp:sat_configfile
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¶
newRamp:superbias_configfile
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¶
newRamp:refpix_configfile
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.
Hint
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¶
newRamp:linear_configfile
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.
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.
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 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.
Simulating WFSS data with Mirage¶
Mirage can be used to simulate Wide Field Slitless Spectroscopy (WFSS) mode data for NIRCam and NIRISS, using the wfss_simulator.py module. To produce these simulations, Mirage constructs one or more imaging mode seed images, along with an associated segmentation map. These seed images and segmentation map are then passed to the disperser software, which is in the NIRCAM_Gsim package. The disperser then takes the seed images, along with an optional input file containing object spectra, and disperses the signal across the detector in the same manner as the NIRCam and NIRISS grisms.
This mode generally uses more input compared to the creation of imaging mode data, as spectral information on the input sources may be provided. There are two methods that spectral information
yaml file: must specify wfss mode and grism_source_image = True. The appropriate grism must be specified, as well as a crossing filter
Inputs¶
There are three types of inputs that can be used to create WFSS data. The first is the same yaml parameter file that is used when creating imaging mode data. Along with the yaml files, the appropriate ascii source catalogs must be provided. The third input, which is optional, is an hdf5 file that contains the spectra for some or all of the targets that are in the source catalogs. Below we describe how to use these inputs to create WFSS data.
Note that when using yaml files as inputs, at least one of these files must have the mode set to “wfss”, grism_source_image set to True, and a grism placed in the appropriate filter or pupil entry. This will be done automatically for the appropriate files during the yaml generation process if generating yaml files from an APT proposal.
Single yaml file¶
In the simplest case a single yaml parameter file is provided to the WFSS simulator module, along with a source catalog containing target magnitudes in a single filter. In this case, Mirage converts the provided magnitude values to flux densities, and the disperser assumes a flat continuum spanning the entire wavelength range of the filter/grism combination.
If the source catalog contains magnitudes in multiple filters, Mirage will, for each source, linearly interpolate the source magnitudes in order to construct a continuum spectrum. If the provided magnitudes do not cover the entire wavelength range necessary for the dispersion, then Mirage will optionally extrapolate the continuum spectrum to cover the full wavelength range.
Tip
In this case where only ascii source catalogs are provided, source spectra will not contain any features (emission, absorption), but will rather be smooth continuum spectra. In order to simulate sources with emission or absorption features, this information must be added via the hdf5 file described below.
Multiple yaml files¶
Another way to produce data with smooth continuum spectra is to provide multiple yaml files, where each yaml file will produce a seed image through a different filter. In this case, the mutiple seed images will be used to calculate source flux densities, rather than these calculations being done using the source catalogs as input. One of these yaml files must specify WFSS mode with the requested grism, as described above. The other yaml files should specify imaging mode. As this method produces the same output as that when a single yaml file and source catalog with multiple magnitude columns is provided, but with more calculations taking a longer time, we recommend against using this strategy.
Yaml file plus SED file¶
In order to create simulated data with more realistic spectra, users can provide an optional hdf5 file that contains spectra for some or all of the targets listed in the source catalogs. The spectra in this file can have any shape, and can include emission and absorption features. The spectrum for each source is contained in a “dataset”, which is read in as a python dictionary containing “wavelengths” and “fluxes” keys. The values associated with each of these fields is a list of floating point numbers. Units can be specified by adding a string as a dataset attribute. If no units are provided, Mirage assumes that wavelengths are in units of microns, and flux densisites are in units of F_lambda (erg/sec/cm:sup:2 /A). Mirage contains functions that can be used to create hdf5 files with their target SEDs.
Tip
The NIRISS WFSS example notebook shows examples of how to create your own hdf5 catalog file, and how to create WFSS data using the methods described above.
MIRAGE Quick Start¶
Table of Contents: * Getting Started * Create ``mirage` input yaml files from an APT file <#make_yaml>`__ * Single image simulation * Create simulation with one command * Running simulator steps independently * Running multiple simulations * Running in series * Running in parallel * Example observation list file * Example yaml file
Getting Started¶
Important: Before proceeding, ensure you have set the MIRAGE_DATA environment variable to point to the directory that contains the reference files associated with MIRAGE.
[ ]:
import os
# For examining outputs
from glob import glob
from scipy.stats import sigmaclip
import numpy as np
from astropy.io import fits
from astropy.visualization import simple_norm
import matplotlib.pyplot as plt
%matplotlib inline
[3]:
# Import top level functions
from mirage import imaging_simulator
from mirage.apt import apt_inputs
from mirage.yaml import yaml_generator
# Import the three steps of the simulator.
from mirage.seed_image import catalog_seed_image
from mirage.dark import dark_prep
from mirage.ramp_generator import obs_generator
### Createmirageinput yaml files from an APT file
For convenience, observing programs with multiple pointings and detectors can be simulated starting with the program’s APT file. The xml and pointings files must be exported from APT, and are then used as input into a tool that will generate a series of yaml input files.
[ ]:
apt_xml_file = 'my_apt_file.xml'
apt_pointing_file = 'my_apt_file.pointing'
[ ]:
catalogs = {'nircam': {'sw': ['nrc_ptsrc_1.cat', 'nrc_ptsrc_2.cat'],
'lw': ['nrc_ptsrc_lw_1.cat', 'nrc_ptsrc_lw_2.cat']},
'niriss': ['niriss_ptsrc_1.cat', 'niriss_ptsrc_2.cat']}
backgrounds = ['low', 'medium']
[ ]:
# Create a series of data simulator input yaml files
# from APT files
yam = yaml_generator.SimInput()
# Point to the xml and pointing files from your APT proposal
yam.input_xml = apt_xml_file
yam.pointing_file = apt_pointing_file
# Output directory for the collection of yaml files
yam.output_dir = './yaml_files'
# Output directory for the simulated observations
yam.simdata_output_dir = './imaging_data/'
# Observation table that lists the source catalogs to use with each filter/observation
yam.observation_table = observation_list_file
# Output data type. "raw", "linear", or "linear,raw" for both
yam.datatype = 'raw'
# Optional parameters
yam.use_JWST_pipeline = True
yam.use_linearized_darks = True
# Create the yaml files
yam.reffile_setup()
yam.create_inputs()
[ ]:
# Look at the list of files generated
yaml_files = glob('./yaml_files/*yaml')
## Create simulation with one command
This will take several minutes to run. For a better idea of what Mirage is doing, skip down several cells to the Running simulator steps independently section¶
The imaging_simulator function will run all three steps of the simulator. This convenience function is useful when creating simulated imaging mode data. WFSS data will need to be run in a slightly different way.
[ ]:
test_yaml_file = yaml_files[0]
[ ]:
# imaging_simulator is a wrapper around all 3 steps of Mirage
img_sim = imaging_simulator.ImgSim()
img_sim.paramfile = test_yaml_file
img_sim.create()
## More detail on what’s going on: Running simulation steps independently
First generate the “seed image”¶
This is generally a 2D noiseless countrate image that contains only simulated astronomical sources.
A seed image is generated based on a .yaml file that contains all the necessary parameters for simulating data. An example .yaml file is shown at the bottom of this notebook.
[ ]:
# Generate the seed image
cat = catalog_seed_image.Catalog_seed()
cat.paramfile = test_yaml_file
cat.make_seed()
Look at the seed image¶
[ ]:
# Need to flip the image vertically in order to match what ds9 would show
def show(array, title ,min=None, max=None):
plt.figure(figsize=(12,12))
if min is None and max is None:
norm = simple_norm(array, 'log', percent=99)
else:
if min is None:
min = np.min(array)
if max is None:
max = np.max(array)
norm = simple_norm(array, 'log', min_cut=min, max_cut=max)
plt.imshow(array[::-1,:], norm=norm)
plt.title(title)
plt.colorbar().set_label('DN$^{-}$/s')
[ ]:
show(cat.seedimage,'Seed Image', max=100, min=0)
Prepare the dark current exposure¶
This will serve as the base of the simulated data. This step will linearize the dark current (if it is not already), and reorganize it into the requested readout pattern and number of groups.
[ ]:
d = dark_prep.DarkPrep()
d.paramfile = test_yaml_file
d.prepare()
Look at the dark current¶
[ ]:
# For this, we will look at an image of the final group minus the first group
exptime = d.linDark.header['NGROUPS'] * cat.frametime
diff = (d.linDark.data[0,-1,:,:] - d.linDark.data[0,0,:,:]) / exptime
show(diff,'Dark Current Countrate', max=0.1, min=0)
Create the final exposure¶
Turn the seed image into a exposure of the proper readout pattern, and combine it with the dark current exposure. Cosmic rays and other detector effects are added.
The output can be either this linearized exposure, or a ‘raw’ exposure where the linearized exposure is “unlinearized” and the superbias and reference pixel signals are added, or the user can request both outputs. This is controlled from within the yaml parameter file.
[ ]:
obs = obs_generator.Observation()
obs.linDark = d.prepDark
obs.seed = cat.seedimage
obs.segmap = cat.seed_segmap
obs.seedheader = cat.seedinfo
obs.paramfile = test_yaml_file
obs.create()
Examine the final output image¶
Again, we will look at the last group minus the first group
[ ]:
with fits.open(obs.raw_output) as h:
lindata = h[1].data
header = h[0].header
[ ]:
exptime = header['EFFINTTM']
diffdata = (lindata[0,-1,:,:] - lindata[0,0,:,:]) / exptime
show(diffdata,'Simulated Data',min=0,max=20)
If you have multiple exposures that will use the same dark current image (with the same readout pattern, subarray size, and number of groups), you can feed the output from the initial run of dark_prep into future runs of the obs_generator, to save time. This can be accomplished with the imaging_simulator.py code, as shown below. (Note that time savings are minimal in this case, where the readout pattern is RAPID and there are only a handful of groups. This means that no averaging/skipping
of frames has to be done within dark_prep.py)
[ ]:
# Now that the linearized dark product has been created, if you want to use it
# when running the simulator with a different yaml file (or repeating the run
# with the same yaml file) you can provide the filename of the dark product, and the
# dark_prep step will be skipped.
# NOTE: if you use the same dark product for multiple exposures, those exposures
# will contain exactly the same dark signal. This may or may not be advisable, depending
# on your goals for the simulated data.
img_sim_same_dark = imaging_simulator.ImgSim()
img_sim_same_dark.paramfile = second_yaml_file
img_sim_same_dark.override_dark = 'jw44444001001_01101_00001_nrcb1_uncal_linear_dark_prep_object.fits'
img_sim_same_dark.create()
## Running Multiple Simulations
Each yaml file will simulate an exposure for a single pointing using a single detector.¶
### Function to simulate multiple detectors/pointings in series
[ ]:
def make_sim(paramlist):
'''Function to run many simulations in series
'''
for file in paramlist:
m = imaging_simulator.ImgSim()
m.paramfile = file
m.create()
[ ]:
from multiprocessing import Pool
n_procs = 3 # number of cores available
with Pool(n_procs) as pool:
pool.map(make_sim, yaml_files)
## Example yaml input file
Entries listed as ‘config’ have default files that are present in the config directory of the repository. The scripts are set up to automatically find and use these files. The user can replace ‘config’ with a filename if they wish to override the default.
In general, if ‘None’ is placed in a field, then the step that uses that particular file will be skipped.
Note that the linearized_darkfile entry overrides the dark entry, unless linearized_darkfile is set to None, in which case the dark entry will be used.
```yaml 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: RAPID #Readout pattern (RAPID, BRIGHT2, etc) overrides nframe,nskip unless it is not recognized ngroup: 3 #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 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: 0.0 #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: jw44444024002_01101_00001_nrcb1_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: 44444 #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: ‘024’ #Observation Number observation_label: Obs2 #User-generated observation Label visit_number: ‘002’ #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: ‘V44444024002P0000000001101’ #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)
```
[ ]:
API Documentation¶
Contributors¶
Mirage is based on early NIRISS simulator software written by Kevin Volk. It has been developed by a group of core contributors from STScI: