NIRSpec MOS - Deep Extragalactic Survey APT Guide

This is a NIRSpec MOS deep extragalactic survey use case.  The APT step-by-step instructions are provided in detail here.

On this page

MOS design considerations and APT workflow

In this article we describe how to implement the Deep Extragalactic Survey science use case observations in APT version 25.4. We will use the MSA planning tool (MPT). Here, we focus on the available design choices, and the rationale for selecting from the many available options. We will walk through each section of MPT (CatalogPlannerPlans) to create example observations, and in the end we will add parallel NIRCam imaging. Choices and tradeoffs were made given our current pre-flight state of knowledge of the instrument performance.


As stated in the Science Goals, we use the GOODS-S Catalog from Momcheva et al. (2016), which is publicly available. Instructions for filling out MPT’s catalogs pane can be found in the MPT Catalogs article. In brief, once a catalog is uploaded, some catalog parameters must be specified in the catalogs pane.  We enter an astrometric accuracy of 10 mas, since our catalog was constructed from HST imaging which typically has this accuracy. We also set “Pre-Imaging Availability” to “Not Required,” since pre-imaging in this case refers to NIRCam pre-imaging and we have HST imaging. The reference position type and coordinates need not be edited for normal use cases such as ours. Finally, following the approach we outlined in the Observing Strategy, we define primary and filler targets with photometric redshifts at 5 < z < 6  (542 galaxies) and 2 < z < 5 (7559 galaxies).  

Running the planner

The planner tab contains many options for specifying how MSA configurations are designed. The MPT article gives instructions for how to complete this section. For this use case, we make the following choices:

  • Aperture PA (APA): This parameter describes the position angle of the MSA, and consequently, the position angles of the slitlets in the configuration. For a given target, position angles are constrained by when the field is visible to JWST. Hence, we use the JWST General Target Visibility Tool (GTVT) to find reasonable APAs. For GOODS-S, we find that APAs between 30° and 210° will be available from August 2019 to February 2020. For the case shown here, we test an APA of 60°. 

    We recommend that users test several angles using the steps that follow, to determine whether multiplexing (science) results depend on the assigned orientation. In general, specifying a tightly constrained orientation is discouraged, as it may decrease scheduling efficiency.

  • Primary and Filler Candidate Lists: Here, we select the candidate lists that we defined on the catalogs pane. 

  • Slitlet Length: Here, we have the option to choose whether the slitlets are 1, 2, 3, or 5 shutters (0.2” × 0.5”) in length. While longer slitlets could offer more pixels for background subtraction, they will also reduce the number of slits that can fit on a configuration, thereby decreasing multiplexing. Therefore, in this use case, we select a three-shutter slitlet. The source will always be in one slitlet and the other two slitlets will be used for background.

  • Source Centering Constraint: Since the MSA is a fixed grid, sources cannot be perfectly centered in their respective shutters. Hence, the source centering constraint sets a threshold for how off-center sources can be. The most lenient option, “Unconstrained” will allow the centers of our target galaxies to fall behind the bars that separate the MSA shutters. While this option may be reasonable for large galaxies, it will also require significant corrections for slit-losses. Alternatively, the most stringent option, “tightly constrained,” would require the smallest slit loss corrections, but it would ultimately reduce multiplexing, especially for our somewhat smaller set of primary sources. While the pipeline correction for slit-losses on point sources is straightforward, for galaxies it is not applied.  It is much more uncertain and must be applied by the user. As a compromise between slit-loss corrections and multiplexing efficiency, we choose “Midpoint” as our source centering constraint. The precise definitions of the available source centering constraints are given in the NIRSpec MPT - Planner article. 

  • Dithering: An MSA observation has options for nods and dithers, as described in NIRSpec MOS Dither and Nod Patterns. We choose to nod, taking an exposure in each shutter of our three-shutter slitlet.  Since nod positions can serve as dithers, we choose not to add any additional dithers. This choice increases efficiency in two ways.  First, we do not have to reconfigure the MSA, saving 90 seconds of overhead. Second, we do not suffer multiplexing losses, due to the requirement that our sources be observable in two configurations, rather than one. The down-side to this choice is that our spectra will have a wavelength gap, due to NIRSpec’s chip gap.  We accept this compromise.  We note that adding a 20” Fixed Dither to cover the chip gap would still result in half the exposure time, and a non-uniform signal-to-noise, over certain wavelengths.   For users concerned about wavelength coverage, the NIRSpec team has provided the MSA Spectral Visualization Tool  to quantify the wavelengths that are missed for each slit in a given configuration.

  • Exposure Setup: Here, we define the exposures, entering the numbers that we determined during the ETC study. We add two rows to the exposure table for G140M/F100LP, and one each G235M/F170LP and G395M/F290LP (see Figure 1).

    Figure 1. Exposure table from MPT

    The exposure table in MPT specifies the grating/filter combination, readout pattern, groups, and integrations. The selected groups and integrations are for a single nod, and the last two columns ("Total Integrations" and "Total Exposure Time") combine all nods and dithers.
    If we had specified a single exposure with 22 groups and 8 integrations for G140M/F100LP, each exposure of the nod would be longer than 10,000 s, and would violate the maximum exposure time allowed by JWST. We select Autocals  =  None; this approach will use archived flat fields and wavelength calibrations from commissioning, rather than observing new (contemporaneous) calibrations. At present, the NIRSpec team does not recommend autocals. The last two columns show the total number of integrations, and the total exposure time in each configuration. In this case the number of integrations is 12 or 3: the number of integrations per nod, times the number of nods. Lastly, the option to select multiple sources per row will increase multiplexing by allowing spectral overlap. Since we do not want our spectra to be contaminated, we do not check this box. 

  • Search Grid: Here, we define the area over which MPT will search to optimize the placement of source in shutters. We choose 4 specific NIRSpec pointings that will create a uniform survey area in both NIRSpec and our NIRCam parallels.  For each one, we will create a separate plan, containing a single pointing of the MSA. The central positions of these search grids are given in Table 1.  

    Table 1.  Four pointing positions

    Plan NameRADec
    GOODS-S_APA_60_pointing103 32 35.11 -27 46 09.5
    GOODS-S_APA_60_pointing203 32 22.68-27 47 48.9
    GOODS-S_APA_60_pointing303 32 42.55-27 48 59.9
    GOODS-S_APA_60_pointing403 32 30.11-27 50 38.2

    We use a relatively small search height and width (3”), to keep the pointings close to the central positions, but still allow some optimization of the spectroscopic sample. Lastly, we specify a “Search Step Size” of 0.1 arcsec. This small step size results in 961 pointings that will be tested, in order to find the  one with the largest number of sources. A search step size smaller than the width of the shutter can improve multiplexing as is explained in the Parameter Space article.  

  • Parameters:  A few options remain before we can create our plan.  
    1. The “Use Weights” checkbox will allow target weights to be used in determining the most optimal MSA configurations. This parameter is especially useful for cases where users have primary candidates with different priorities.  For simplicity, we do not use weights in this use case.
    2. The “Enable Monte Carlo” checkbox will tell MPT to shuffle the input catalog, by a number of times specified in the box. This feature is useful, because MPT fills the configuration using the ordering of sources in the catalog. If "Enable Monte Carlo" is selected, and weights are present in the catalog, MPT will shuffle the catalog and then sort by the weights. This functionality is desirable for shuffling within some category of sources that have the same weight. 
    3. The number of configurations is one, because we are making a separate plan for each pointing, and we do not have any dithers that require a second configuration at a nearby pointing. It is worth noting that the users should remember to add a number in this box in most cases. The default behavior for an empty box is to make however many configurations are required to observe all of the primary targets. This approach can take quite some time to calculate.
    4. Lastly, we named the plan GOODS-S_APA_60_pointing1, and clicked the “Generate Plan” button. After completing this plan, we change the plan name and coordinates following Table 1, and made three more plans, using the same parameters that we have outlined above.

Examining the plans and creating observations

After making the four plans, we can examine them in the “Plans Tab.” Detailed instructions on how to examine plans are given in the NIRSpec MPT - Plans article. Before creating an observation, we merge our four plans into a single plan, using the “Merge Plans” button.  We name the resulting plan “GOODS-S-4point”. Having all of our configurations and pointings in a single plan allows us to create a single-observation, which we do using the “Create Observations” button.  The benefit of “Merge Plans” is that we ensure that the four pointings will be executed at the same position angle, preserving the 2 × 2 mosaic that we have created. In some cases, plan merging can save overhead by reducing the number of required visits (and target acquisitions).

Overall, this merged plan contains 79 primary targets and 117 filler targets. In this case, the filler targets are observed in all of the nods; this is likely a consequence of the high space density of objects in our catalog, and the fact that we only use a single configuration, with no dithers. As we mentioned above, users are encouraged to compare the multiplexing results at multiple viable position angles, in order to assure that the science goals can be met at the position angle that will be assigned by STScI in the long range plan. 

Examining the observations 

After creating our observation with MPT, we can examine the results by selecting the observation in the tree editor. The following points are worth understanding:

  1. We see that the observations are broken into four visits. This result is expected, since the four pointings are separated by distances greater than the visit splitting distance (40” for GOODS-S).  Each will require a separate guide star and MSA target acquisition.

  2. The observation template allows us to add coordinated parallels by checking the “coordinated parallels box.”  We choose this option, and a pulldown menu appears. We select the only available option “NIRSpec MOS-NIRCam Imaging.”  This selection causes a tab to appear below for defining the NIRCam parallels.  We describe the procedure for adding these images below.

  3. We see that the observations sum to 186,480 s (51.8 hours) of science time, and 239,804 s (66.6 hours) clock time when overheads are included.

  4. The pre-image availability should say “not required,” since we are using catalogs based on HST images, and we therefore do not need to take NIRCam pre-imaging.  

  5. MSATA (MSA Target Acquisition) should be selected as the “TA Method,” in order to appropriately model the observing overheads.  No further steps are required to define TA at the proposal stage.  Tools and documentation will be forthcoming to help plan TA for accepted proposals.

  6. The “Science Parameters” box shows a list of exposures.  Since we have selected NIRCam parallels, a pull down menu labeled “Dither Type” appears. The options specify a set of “compromise dithers” to help sample the NIRCam PSF. We describe this below, where we define the NIRCam parallel exposures. 

  7. The final box, “Confirmation Images” allows the user to define NIRSpec images to be taken after target acquisition.  These images, taken through a configured MSA, can be useful for verifying that the desired sources are in the slitlets.  At present, confirmation images cannot be used when coordinated parallels are in place. Hence, we see that the confirmation image pull-down menu is greyed out. In the future, it may be possible to obtain confirmation images for observations that include coordinated parallels. Additional information on confirmation images is in the NIRSpec MOS Operations - Confirmation Images article. 

  8. Since this use-case presents a “proposal” rather than a flight-ready program update, we navigate to the special requirements tab and add an “On hold for orient assignment” special requirement.  This ensures that the program does not execute until STScI assigns an aperture position angle and the users re-plan their MOS observations to that value.

NIRCam parallels

To define the NIRCam parallel imaging, we navigate to the NIRCam imaging tab on our NIRSpec observation, which was created when we selected coordinated parallels (as described above). We leave a thorough description of NIRcam imaging to NIRCam APT documentation and use cases noting that the same considerations apply here.  However, the following key points are noted for planning NIRCam parallels with NIRSpec observations:  

  1. The exposure table for NIRCam must have the same number of rows as NIRSpec, 16 in this use case. The NIRSpec observations have four rows at each of the four pointings: 2 for G140M/F100LP (recall, a single exposure was longer than 10,000 s), 1 for G235M/F170LP, and 1 for G395M/F290LP. Therefore, we add 16 NIRCam exposure specifications.  Each of these 16 will have 3 dithers, corresponding to the 3 NIRSpec nod points that we specified above.  

  2. Each NIRCam exposure must be specified to fit within the NIRSpec exposures.  APT will give errors if the exposures are too long, but will not provide a warning if the NIRCam exposures are substantially shorter than the available parallel slot.  An easy strategy is to increase the NIRCam exposure times just until the error appears, and then reduce it slightly to make the error disappear. For this use case, we add exposures in several broad bands, placing the bluer bands of NIRCam in parallel with the longer G140M/F100LP observations. Deeper blue imaging is often required for finding very high-redshift galaxies, so this approach is probably close to some use cases. If this non-uniformity is undesirable, the longer NIRSpec exposures could be broken into multiple shorter exposures when creating the observation in MPT. However, this strategy would result in extra overheads for exposure setup, and increased read noise if the number of groups is reduced.

The NIRCam observations will be dithered following the NIRSpec observations. NIRSpec is doing the “driving.” In this case, we have specified 3 in-shutter nods.  Since NIRSpec’s aperture position angle (APA) is not aligned with NIRCam’s, the nods will yield sub-pixel dithers that can help with drizzling the undersampled NIRCam PSF.  However, an option for further dithering, optimized for NIRCam, is available.  When we specified that NIRCam parallels should be added to the template, a pull-down menu to specify these dithers appeared on the “NIRSpec Multi-Object Spectroscopy” tab of the observation. These “compromise dithers” are listed in Table 2.

Table 2. Dithering options for NIRSpec observations that have NIRCam parallel imaging

DithersIndexX (arcsec)Y (arcsec)










These small shifts will move spectroscopic targets by a small amount along the slitlets, in order to improve sampling of the NIRCam PSF.  They are defined along the axes of the NIRSpec slitlets, and are small enough so that NIRSpec targets are not significantly moved out of their slitlets. In this use case, for simplicity, we do not add extra compromise dithers. We note that adding them, at this stage, will double or triple the total exposure times in the NIRSpec observations. Therefore, it is essential to plan ahead, and create MOS observations with half or one third of the total desired exposure time, if the compromise dithers are to be added. 

Finally, with NIRSpec MOS + NIRCam parallels, data volume considerations are a concern. Therefore, we choose the DEEP8 NIRCam detector readout pattern, which produces the lowest data volume. Each visit in this program uses 37 Gb in a 17 hour period, which is just under the recommended limit.  

Visualizing our observations

We use Aladin to visualize the NIRSpec and NIRCam observations, and the results are shown in Figure 2. From MPT’s “Plans” tab, we click the “send to Aladin” button to over-plot red diamonds on all of the targets that will be observed with NIRSpec. 

Figure 2. NIRSpec and NIRCam observations for all four pointings are visualized in Aladin

Red diamonds show the positions of sources that could be observed in one of our 4 configurations.

Visit Planner

Before submitting our proposal, we run the visit planner to ensure that our observations can be scheduled.   More details on the visit planner can be found in APT’s Visit Planner Documentation.   The Figure 3 shows that the observations in this use case can be scheduled from 27 July 2019 to 27 October 2019 and 10 November 2019 to 5 February 2020. 

Figure 3.

Running the visit planner shows that each of the four visits can be scheduled, over a relatively wide range of dates. More details on the scheduling constraints can be fond by expanding the grey arrow beside each listed visit.

APT file

The APT file containing the plans described above can be found in the link below. 

Example APT file. This is the APT file used to demonstrate the complete example in this article.


Curtis-Lake, E., et al. 2016, MNRAS, Vol. 457, issue 1, p. 440
Non-parameteric analysis of rest-frame UV sizes and morphological disturbance amongst L* galaxies at 4 < z < 8

Grogin, N.,et al. 2011, ApJS, Vol. 197, Issue 2, article id. 35
CANDELS: The Cosmic Assembly Near-infrared Deep Extragalactic Legacy Survey

Momcheva, I. G., et al. 2016, ApJS, Vol. 225, Issue 2, article id. 27
The 3D-HST Survey: Hubble Space Telescope WFC3/G141 Grism Spectra, Redshifts, and Emission Line Measurements for ~100,000 Galaxies

Rigby, J. R., et al. 2015, ApJL, Vol. 814, Issue 1, article id. L6
C III] Emission in Star-forming Galaxies Near and Far

Tremonti, C. A., et al. 2004, ApJ, Vol. 613, Issue 2, 898
The Origin of the Mass-Metallicity Relation: Insights from 53,000 Star-forming Galaxies in the Sloan Digital Sky Survey



Latest updates