MIRI Medium Resolution Spectrometer End-to-End Tutorial: From Planning to Simulations to Analysis

The article demonstrates a simple observing case on how to plan, simulate, reduce, and analyze observations for a JWST Mid-Infrared Instrument (MIRI) Medium Resolution Spectrometer (MRS) program.


The observing case is to obtain a MIRI-MRS spectrum of a late M type star without circumstellar material.  The reader is guided through the use of the ETC and APT in the planning phase to determine how to observe the target.  Then, the reader is guided through the use of simulation software named “MIRISim”, which generates simulated data for the MRS.  Next, reducing the simulated data using the JWST data reduction pipeline is described.  Finally, the reader is presented with instructions on how to perform a simple analysis of the spectra obtained from the JWST pipeline, using Cubeviz.


An observer will have in mind the kind of observation needed to address a scientific concern.  They will want to observe a particular kind of object or individual object(s), they will want to use a certain mode of observing (e.g., imaging, spectroscopy), and they will want to observe over some wavelength range. They determine if a given instrument can perform the type of observation they want, and, if so, they use various tools and sources of information that are available to determine exactly how to perform this observation to obtain the data they seek.  In the present observing case, a simple MRS observation of a point source with only a stellar spectrum is presented. This observing scenario will likely be of general interest to the prospective observer.

Exposure Time Calculator

Often the first tool a prospective observer will use is an Exposure Time Calculator (ETC).  Many observatories or instrument teams make ETC’s available for their instruments.  The ETC allows a user to determine how an instrument will perform when observing a certain object with specified properties for a given set of exposure parameters. For planning MRS or any other JWST observations, the JWST ETC may be used.  This ETC makes use of Pandeia (Pontoppidan et al. 2016).

In the JWST ETC, one first specifies an astronomical scene.  Here, only one point source is included.  It is assumed to be a continuum source whose spectral shape is that of a PHOENIX stellar photosphere model (Hauschildt et al 1999) for an M5 V star, with 3500K effective temperature and log(g) = 5.0.  Both redshift and extinction are assumed to be zero. The star is assumed to have a flux density of 100 mJy at 10 μm.  As it is a naked photosphere, the continuum flux density over MRS wavelengths is roughly inversely proportional to wavelength squared, which is a fairly steep drop-off to longer wavelengths.

Once the astronomical scene is specified, the ETC can perform calculations to determine the signal-to-noise ratio (S/N) that would be obtained for a given set of exposure parameters. Under the Calculations tab in the ETC, one begins by selecting the drop-down menu for MIRI and selecting MRS. A new calculation appears underneath.  One then selects this calculation, and the window to its right is activated.  The Scene is what has already been specified for the astronomical scene.  Under Backgrounds, one may have the ETC determine the background for a given date, or instead one may use a pre-set background; in this case, a pre-set Medium background was used.  Under Instrument Setup, one specifies the MRS channel and dispersion setting to be used.  Because of the aforementioned inverse square wavelength dependence of the flux density, it is best to determine the optimal exposure parameters at longer wavelengths first.  There are 3 wavelength dispersion settings—Short, Medium, and Long—for each channel of the MRS, so that a full spectrum from 5 to 28 μm is composed of 4 × 3 = 12 spectral segments.  The MRS operates one wavelength dispersion setting at a time, so that the spectral segments for that setting in all 4 channels are obtained simultaneously.  E.g., 1-Short, 2-Short, 3-Short, and 4-Short would be obtained at the same time.  Determining exposure parameters at shorter wavelengths first for this observing case would be counter-productive, as an exposure time sufficient to obtain the desired S/N at shorter-wavelengths may yield insufficient S/N for a longer-wavelength channel in the same wavelength dispersion setting.  Under the Strategy tab, “IFU Nod In Scene” was chosen, which would simulate subtracting sky from the point source from the other dither positions.  The aperture radius was set to 0.5 arcseconds, while the “Nod position in scene” was allowed to vary from (1”, 1”) at the shortest wavelengths up to (1.5”, 1.5”) at the longest wavelengths, allowing for the growing size of the PSF and the larger field-of-view in the longer-wavelength channels than in the shorter-wavelength channels.

S/N > 50 for all wavelengths shorter than 26 μm was desired.  Under the Detector Setup tab, this was obtained by setting the Subarray to FULL, the readout pattern to FAST, and using the following number of groups/integrations/exposures: 48/1/2 (short disperser setting), 68/3/2 (medium disperser setting), and 81/5/2 (long disperser setting).  The number of exposures was set to 2, as the IFU Nod-In-Scene option for background assumes a 2-point dither, so 2 exposures of this simulated a 4-point dither, which is the desired dither pattern here.  Following the MIRI Generic Best Practices, the number of groups per integration was kept under 360.  The groups per integration were first set with the number of integrations equal to 1, but it was found from the ETC that the data would saturate unless the number of integrations was increased so that the number of groups per integration could be decreased.  This was done until the lowest number of integrations was found that, when the number of groups per integration were set sufficiently high, the desired S/N of 50 at the longest wavelengths of segments 4A and 4B and at 26 μm in the 4C segment were attained without generating saturation warnings in the ETC.  The S/N obtained from these settings is demonstrated in a plot generated by the ETC, shown in Figure 1.  In this figure, each of the 12 segments is a different color, to aid in distinguishing it from the other 11 segments.  The S/N rises as high as ~1050 in the 1C segment.

The ETC workbook in which all these calculations were performed is intended to be made available to the public in the near future.

Figure 1. A plot of the S/N for a naked photosphere obtained assuming the observation setup described in the ETC section of the text.

Astronomer’s Proposal Tool

After determining exposure parameters in the ETC, the next step is to create the program in the Astronomer’s Proposal Tool. For this tutorial, APT version 25.4.4 was used.  Requested information was provided on the Proposal Information page.  A generic fixed target was created and given RA and Dec approximately in the Taurus-Auriga star-forming region.  A new observation was created, and a MIRI Medium Resolution Spectroscopy template and the generic fixed target were chosen.  Since the target is a simple point source, TA is not needed.  The all-channel 4-point dither for “All” (as opposed to the extended source pattern), in the negative direction was chosen as the MRS dither pattern.  For this observing case, it would not matter if the positive direction were chosen for the MRS dither pattern.  This is a dither pattern that will likely be used often.  Simultaneous imaging was allowed, as this will often be the case, and the imager subarray was set to Full.  In the Exposure Parameters field, entries were added for the 3 dispersion settings—short, medium, and long.  The filter for the simultaneous imaging was chosen to be F560W, and the exposure parameters determined from the ETC were entered here.  This is a single tile observation, not a mosaic, so the Mosaic Properties section was left unchanged.  No special requirements were added.  The total data volume reported by APT was 20,829 MB.  After running Smart Accounting, the total science time for this program is 2.03 hours, and the total charged time for this program is 3.50 hours.

The apt file corresponding to this APT program is here: star_mrs_tutorial.aptx 

Simulating MIRI-MRS Data with MIRISim

For the MIRI instrument, data simulation software called MIRISim exists and is publicly available.  This software is capable of simulating data obtained from the MIRI instrument using its various modes; here, MIRI-MRS data is simulated.  To install MIRISim, download the bash script from the MIRISim website and run it.  This may require some packages to be installed first per the MIRISim installation notes.  Once it is installed, create a directory to hold all the MIRISim simulations and change directory to it.  Once MIRISim is activated, run the command:

MIRISim --generate-configfiles

This will generate the configuration files that specify the details of the MIRISim simulation.  Once these are generated, MIRISim may be run. For beginners, it is perhaps most helpful to look at the 3 configuration files named mrs_simulation_commented.ini, scene_commented.ini, and simulator_commented.ini.

The first configuration file, mrs_simulation_commented.ini, allows one to set the exposure parameters.  This particular file has comments describing the meaning of the various fields that need to be specified.  The ConfigPath variable is where one specifies the portion of the MIRI mode to be used in the simulated observation.  For this case, MRS_1SHORT is chosen for the first simulation, while MRS_1MEDIUM and MRS_1LONG are used for the other dispersion settings’ simulations.  For the dither pattern, the start index is set to 1, the number of dither positions is set to 4, and the dither pattern file is mrs_recommended_dither.dat.  Under the MRS_configuration section, the disperser is SHORT (and then MEDIUM and later LONG for the other dispersion settings’ simulations).  The detector is BOTH, since this simulates obtaining data on both of the MRS detectors at once.  The readout mode, exposures, integrations, and frames are Fast, 1, 1, and 48 for the SHORT dispersion setting, as determined from working in the ETC earlier (and these would be modified according to the parameters for the MEDIUM and LONG dispersion settings, also as determined from the ETC exercise).

The second configuration file, scene_commented.ini, is where one specifies the components of the astronomical scene one is trying to simulate (somewhat analogous to setting up a scene in the ETC).  Again, the comments in this file give helpful directions.  The Background section is where one specifies the characteristics of the background.  For this tutorial, a point source is being simulated, so the Point section following the Background section is retained (and the indented [[sed]] section following it), but all other sections are deleted.  In the Point section, the Type is Point, and the center can be left as “0 0”.  No velocity or redshift are assumed, so they are left to be 0.  In the [[sed]] section, the assumed spectrum of the source is specified.  Here, a PHOENIX model has been assumed for the ETC exercise, so that is specified here as well.  The value for Type in this section is “pysynphot”, the value for family is “phoenix”, the value for sedpars is “3500 0.0 5.0”, the value for wref is 10 (this is the reference wavelength), and the value for flux is 100000.  Thus, the assumed spectrum is a PHOENIX model of a 3500K effective temperature star of metallicity log(z)=0.0 and log(g)=5.0.  The flux of the star is normalized to 100000 μJy at 10 μm wavelength.

The last configuration file, simulator_commented.ini, is largely okay to use as-is, except that mrs_ref_band should be set to SHORT for the SHORT dispersion setting, MEDIUM for the MEDIUM dispersion setting, and LONG for the LONG dispersion setting.  As the file’s comments for this entry indicate, this entry specifies which band of the MRS should be used in the dither reference frame.

With all 3 configuration files set as desired, the simulation may now be run.  When MIRISim has been activated within the folder where all simulations are to be kept, run the following command:

MIRISim mrs_simulation_commented.ini --scene=scene_commented.ini --config=simulator_commented.ini

This will generate the simulated MIRI-MRS data.  If MIRISim does not already have access to CDP files, it will take longer for it to copy those files automatically to a local directory, but if they are already there, then it will not take as long.  When MIRISim finishes, the slope data files for the simulation are located in the /det_images/ subfolder of a folder named according to the date and time the simulation was started.  Figure 2 is a screenshot of ramp data generated for this tutorial, for the short-wavelength MRS detector.

The mrs_simulation config files used for this tutorial are mrs_simulation_star1a3a.ini, mrs_simulation_star1b3b.ini, and mrs_simulation_star1c3c.ini; the scene config files used for this tutorial are scene_star1a3a.ini, scene_star1b3b.ini, and scene_star1c3c.ini; and the simulator config files used for this tutorial are simulator_star1a3a.ini, simulator_star1b3b.ini, and simulator_star1c3c.ini.

Figure 2. A screenshot of ramp data for the short-wavelength MRS detector generated by MIRISim for this tutorial. 

The slices for MRS channel 1 are on the left half, and the slices for MRS channel 2 are on the right half.

JWST Data Reduction Pipeline and MRS Data

The simulations can now be run through the JWST data reduction pipeline.  A broad overview of the steps in the pipeline as they pertain to MIRI data is provided by Gordon et al (2015).  The simulator, MIRISim, will generate as output one file for each exposure at each dither position belonging to each of the short-wavelength or long-wavelength detectors (as specified).  For example, for the SHORT dispersion setting, the number of exposures was set to 1, but both short-wavelength and long-wavelength MRS detectors were requested in the mrs_simulation_commented.ini file, and a 4-point dither pattern was requested, so 1 × 2 × 4 = 8 files were output for the MIRISim simulation of each of the 3 disperser settings.  Altogether, each of the 1 × 2 × 4 × 3 = 24 files output from MIRISim must be processed by the JWST pipeline.

For more on the pipeline itself, including installation instructions, please see the relevant JDOX articles on the pipeline itself, installation, and the file naming convention and data products.

The MIRISim output files are suitable as inputs for the Stage 1 pipeline script, calwebb_detector1.cfg.  This can be accomplished by issuing the following command:

strun /path/to/jwst/pipeline/scripts/calwebb_detector1.cfg name_of_MIRISim_file.fits

After running the MIRISim output files through this script, the resultant outputs are to be run through the Stage 2 pipeline script for spectroscopic data, calwebb_spec2.cfg.  This can be accomplished by issuing the following command:

strun /path/to/jwst/pipeline/scripts/calwebb_spec2.cfg name_of_MIRISim_file_rate.fits

The files output from calwebb_spec2.cfg with filenames ending in “_cal.fits” can then be used in the Stage 3 spectroscopic step cube_build.  The _cal.fits files corresponding to all dither positions for one disperser setting for either the short-wavelength detector or the long-wavelength detector should be specified in an association table that is called when the cube_build step is called.  For more on association tables, including an example of the format for a .json file that includes an association table, please see the JDOX article on Associations (see especially the section entitled "Association generator").  The Stage 3 script calwebb_spec3.cfg can be called for cube building, or the cube_build step can be called in isolation to perform cube building.  To call cube_build alone, issue:

strun jwst.cube_build.CubeBuildStep <name_of_asn_file>.json

Cubes for the MRS are built according to the Modified Shepard method (see Renka 1988).  After performing the cube_build step for both short wavelengths and long wavelengths for a given disperser setting, 4 cubes are created, which are the cubes built from each of the 4 MRS channels for that disperser setting.


The pipeline has now returned 12 cubes—one cube for each of the 3 disperser settings for all 4 channels of MRS.  The cubes output by the JWST data reduction pipeline may now be analyzed.  A software packaged named Cubeviz has been developed at Space Telescope Science Institute for analysis of IFU cubes and is publicly available.  With Cubeviz, one may view the slices of a cube, extract a spectrum from a user-specified region of the cube, view the data quality (DQ) and error (ERR) cubes along with the science (SCI) cube, and more.  Cubeviz is designed to be a tool of general interest and applicability to users with IFU data; for the JWST community, it will be of interest to users of both MIRI-MRS and the NIRSpec IFU.  Cubeviz is currently still under development.

Figure 3. A screenshot of Cubeviz. 

The image plane at left shows a slice in the channel 1 SHORT disperser setting cube produced by the JWST pipeline.  At bottom can be seen a spectrum obtained by summing the pixels highlighted in red in the image slice.
Figure 4. The MRS channel 1 short dispersion setting spectrum of the simulated late M type star, extracted using aperture photometry performed (outside of Cubeviz) on each slice of the cube built by the JWST pipeline. 

The flux calibration had already been applied to the cube spaxels directly by the pipeline, such that the spaxel units are mJy/arcsec2.  The flux density for the extracted region (extraction performed outside of Cubeviz) was determined by multiplying the signal from aperture photometry (which has units of mJy/arcsec2) by the solid angle of a single spaxel.  The PHOENIX model assumed for MIRISim is provided along with the extracted spectrum, for comparison.


The purpose of this tutorial is to guide the user through the entire process of planning a JWST MIRI-MRS observing program, simulating data returned as part of this program, reducing the simulated data, and analyzing the data.  This program simulates a very simplistic observing scenario—observing a point source continuum source.  It is hoped that the user may build upon their experience with this tutorial to design more complex MRS observing programs as they may desire.


Gordon, K. D., et al. 2015, Publications of the Astronomical Society of the Pacific, 127, 696

Hauschildt, P. H., et al. 1999, ApJ, 512, 377

Pontoppidan, K., et al. 2016, Proceedings of the SPIE, 9910, 16

Renka, R., 1988, ACM Transactions on Mathematical Software, 14, 139

Wells, M., et al. 2015, Publications of the Astronomical Society of the Pacific, 127, 646


(enter date using //)

Latest updates
  • (enter date using //)
    Briefly describe change