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.


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.