Step-by-Step APT Guide for NIRSpec MOS Deep Extragalactic Survey

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

Dated material

This example was created pre-launch, and the APT has been updated since its creation. You may see differences in the appearance of the APT GUI and/or the warnings and errors in APT from what is shown herein.

Please refer to JWST Example Science Programs for more information.

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 2020.1. 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 Catalog ingest and each section of the MPT (PlannerPlans) 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.

Concept behind the MPT Plans

Through experimentation with the Microshutter Assembly (MSA) planning tool (MPT), and following the procedures outlined in the MOS science example main article, we determined that four NIRSpec MOS pointings will be required to observe around 200 galaxies at 2 < z < 6.

Determining MSA pointings when parallel observations are needed

We want our NIRCam parallel observations to cover a semi-regular area on the sky (e.g., rectangle). This severely restricts the location of the MSA pointings. To obtain a NIRCam mosaic, MSA points must also have a well-defined mosaic. Therefore, in this use case, we will restrict the MSA pointings to specific regions on the sky.

Restricted MSA pointings are not the default mode in MPT. Generally, MPT finds an optimal set of pointings over the full field, maximizing the number of targets (or target weights) that will be observed. While this approach is advantageous for spectroscopy, it has the disadvantage that any associated NIRCam parallel observations will have non-contiguous area and/or a non-uniform depth.

We choose an area on the sky of 8 × 8 arcminutes, which corresponds to roughly 2 × 2 MSA footprints. In order to define a sample of galaxies in this area, we take the GOODS-S Catalog from Momcheva et al. (2016), and restrict it to a circular region around the coordinates of the center of our pointing RA 03:32:33.00, DEC -27:48:47.0. A 5.5 arcminute radius around this pointing gives a region that will circumscribe an 8 × 8 arcminute square. By using this circular region, which is somewhat larger than the area selected, we ensure that our catalog contains sources that will fill the MSA for any possible aperture position angle that is assigned. In total, this sub-region contains 27,964 objects. 

Words in bold are GUI menus/
panels or data software packages; 
bold italics are buttons in GUI
tools or package parameters.

In order to make efficient use of the MOS, while also carrying out a cohesive science investigation, we define Primary and Filler candidates from our Catalog. For Primary candidates, we choose galaxies with photometric redshifts above 5, where NIRSpec can access both Hα and [CIII], CIII] (in bands 3 and 1, respectively). For Filler candidates, we use galaxies with photometric redshifts at 2 < z < 5. In this use case, lower-redshift galaxies are well suited as Filler targets, since they will typically be brighter than Primary targets. While the MSA planning tool ensures that Primary targets will be observed at all nods and dithers, Filler targets may be observed in only a subset, resulting in reduced sensitivity. 

General Consideration: In the MPT, targets in the Primary list will receive full exposure depth. Targets in the Filler list may not. In other words, there is no guarantee that targets in the Filler list will receive any more depth than a single integration. If the user wants to ensure that their Filler targets receive full exposure depth, these objects should be added to the Primary candidate set and assigned an appropriate weight.


As stated in the Science Goals, we use the GOODS-S Catalog from Momcheva et al. (2016), which is publicly available. Instructions for preparing and ingesting a Catalog for use in MPT can be found in the MPT Catalogs article. In brief, when a Catalog is uploaded as an MSA Catalog Target in APT, some Catalog parameters must be specified. 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 with the requisite accuracy. 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 candidate lists with photometric redshifts at 5 < z < 6  (542 galaxies) and 2 < z < 5 (7559 galaxies).  

Running the MPT Planner

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

  • Primary and Filler Candidate Lists: Here, we select the candidate lists that we defined on the MSA Catalog Target.

  • 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. In the science article, we used the JWST General Target Visibility Tool (GTVT) to find reasonable APAs, and selected an APA of 60° for our tests.

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.

  • Slitlet Length: Here, we have the option to choose whether the slitlets are 1, 2, 3, or 5 shutters in length. Each shutter is 0.27” × 0.53” including the bar).  While longer slitlets could offer more pixels for background subtraction, they will also reduce the number of slits that can fit in an MSA configuration, thereby decreasing multiplexing. Therefore, in this use case, we select a 3 Shutter Slitlet. The source will occupy one shutter and the other two shutters 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 observed 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 of the galaxies in each shutter of their 3 Shutter Slitlet.  Since nod positions can serve as dithers, we choose not to add any more 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 MSA Target Info export file contains the wavelength cutoffs for each slitlet on the MSA. 

  • Gratings/FiltersHere we choose the grating-filter combinations we wish to observe as specified in the Science Goals. We select G140M/F100LP, G235M/F170LP and G395M/F290LP. Lastly, the option to select Multiple Sources per Row will increase multiplexing by allowing spectral overlap. However, 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 sources in MSA 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 MPT 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 MPT Plans.  
  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 MSA 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.   For simplicity, we do not use Monte Carlo shuffling in this example, so we do not check the box for Enable Monte Carlo.
  3. The option to Allow sources in areas affected by stuck open shutters implies that, when selected, the MPT will ignore the stuck open shutters during planning. That is, MSA sources may be positioned in these shutters, or in the area that is normally masked around them. This may help with multiplexing, but since we are looking at faint sources, we would like to avoid any additional contamination of our source spectra. We will plan around these stuck open shutters and leave the checkbox unchecked.
  4. 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. The default in this box is the minimum number needed to complete the Plan. The behavior for a null entry is to make however many configurations required to observe all of the Primary sources. This approach can take quite some time to calculate and will likely generate an unreasonable number of MSA configurations.
  5. 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 of MPT. Detailed instructions on how to examine Plans are given in the NIRSpec MPT - Plans article. Before creating an observation, we can  examine all four Plans together by selecting all of them in the Plan Selection area. Having all of our configurations and pointings selected together allows us to also create a single observation from them, which we do using the “Create Observation” button. 

Overall, this observation created by concatenating the plans contains 79 Primary sources and 120 Filler sources. In this case, the Filler sources 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. We name the resulting observation “GOODS-S-4point”. The benefit of making a single observation from our Plans is that we ensure that the four pointings will be executed at the same position angle, preserving the 2 × 2 pseudo-mosaic that we have created. In some cases, this methodology can save overhead by reducing the number of required visits (and target acquisitions).

Exposure durations in the observation template 

After creating the observation, we need to fill out the exposure duration parameters for our exposures. We define the exposure durations by entering the numbers that we determined during the ETC study.  The first row in the exposure table, for G140M/F100LP, will be used twice per configuration in the bottom table.  This strategy obtains the desired 10 integrations per nod, while avoiding exposure times that are longer than 10,000 s (the maximum exposure time allowed by JWST). We also 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 15 or 3: the number of integrations per nod, times the number of nods.

Figure 1. Exposure table from MOS observation template

The Exposure Specification and Configurations/Pointings tables at the observation level in the Form Editor specify the Grating/Filter combination, Readout Pattern, Groups/Int, and Integrations/Exp. The selected groups and integrations are for a single nod.  The Configurations/Pointings table combines all nods and dithers in the last two columns ("Total Integrations" and "Total Exposure Time").  Note that there are 16 rows total in the Configurations/Pointings Table (4 per configuration); the additional rows can be seen by scrolling in APT.

Examining the observations 

We can now examine the observation. Make sure the observation is selected 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 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 201,360 s (55.93 hours) of science time, and 262,196 s (72.83 hours) clock time when overheads are included. The exact timing in APT results can evolve with time, as STScI improves the timing model. If you are using the latest release of APT, these numbers may be slightly different.

  4. The pre-image availability should say “not required,” since we are using a Catalog 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, as shown in Figure 1. 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 in the template, “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, and the MOS observations will be flagged in APT for an angle assignment, the program will 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 (at short wavelengths) 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. The sizes of these “compromise dithers” are listed in the article on NIRSpec MOS Dither and Nod Patterns.   These small shifts will move spectroscopic targets by a small amount along the slitlets.  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, we would need to decrease the total desired exposure time of the NIRSpec exposures correspondingly 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 41 Gb in about an 18 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 in the toolbar of APT to ensure that our observations can be scheduled. More details on the Visit Planner can be found in APT’s Visit Planner Documentation. Figure 3 shows that the observations in this use case can be scheduled in two windows, approximately 3 months each, over the course of the year.

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 found by expanding the grey arrow beside each listed visit.


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



Latest updates
Originally published