The JWST NIRSpec MSA Configuration Editor is designed to help the user manually create new MSA Configurations or to modify existing ones for application to a MOS observation.

On this page

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

It is possible to create MOS observations without the use of the MSA Planning Tool (MPT). It is also possible to modify MSA configurations that were created from Plans in MPT. This article describes these less common workflows for producing MOS observations that are supported by the MSA Configuration Editor, which is a tool that is accessed directly at the observation level in APT. Among them are:

Modifying an existing MSA Configuration in an observation
Designing a MOS observation using custom MSA Configurations designed from scratch
Importing externally designed MSA Configurations for use in a NIRSPec MOS observation

Additionally, the article Long Slit MOS Observations describes how to use the built-in long slit MSA Configurations for observing extended moving or fixed targets.

The MSA Configuration Editor

The MSA Configuration Editor is a tool that can be accessed through the MOS spectroscopy observation template in the Form Editor of APT. After specifying an entry in the Exposure Specification table of the observation template (Figure 1), an entry can be added to the Configurations/Pointings table, containing one or more MSA configurations for each exposure specification. The MSA Configuration Editor is initiated by clicking Edit Config in the last column of the table, which will pop up a new window that allows the user to create new, or manipulate an existing, MSA Configuration. This tool provides additional functionality for creating and modifying MSA configurations, described below. Configurations can also be imported using the tool. The user has shutter-by-shutter control over an MSA configuration, toggling operable shutters open or closed.

Modifying an existing MSA Configuration

In this section, we are starting from the assumption that a MOS observation has already been generated from a plan created with the MSA Planning Tool. To modify an existing MSA Configuration in this observation, select the observation you wish to modify in the Observation Folder of your APT program, as shown in Figure 1. Make sure you are in the Form Editor (the upper left icon in the APT GUI should be highlighted). Scroll down to the Science Parameters section. The Primary and Filler Candidate lists and Aperture PA used to design the observation in MPT are shown, but are not editable. There are also 2 tables in this section, one called Exposure Specifications, and one called Configurations/Pointings. For each entry in the first table, there can be one or more entries in the second table. If the observation was derived from a plan made in MPT, some of the parameters in the tables will not be editable. Observations designed with MPT are for specific pointings and angles, and changing one or the other could move sources out of their intended slits in the MSA Configuration.

Note that in the Configurations/Pointings table, any nods designed in MPT are shown together on a single row of the table. The column Nod Pattern in Figure 1 indicates 3 shutter slitlet which implies a 3-shutter nod in this example. This table also includes a column indicating the name of the MSA Configuration used. At the right end of the table, there is a column called "Edit Config", with an Edit button on each row to edit the MSA Configuration associated with that exposure. Multiple entries in the Configurations/Pointings table may use the same MSA Configuration. Clicking that button will bring up a window, called the MSA Configuration Editor.

The MSA Shutter View

In this and the following sections, as we walk through one workflow, we will point out other features and options of the MSA Configuration Editor that may be useful for other workflows.

When the MSA Configuration Editor is opened on an exposure made with MPT, the MSA Shutter View is presented, as shown in Figure 2. This view is similar to the MSA Shutter View used in MPT and discussed in the MPT - Plans article. Figure 2 shows the MSA projected toward the sky, displaying the planned Primaries, Fillers and/or Contaminants for the exposure. From left to right and top to bottom, the 4 quadrants are Q3, Q1, Q4, and Q2. Between quadrants Q3 and Q4 are the outlines of the IFU aperture and 4 of the fixed slits. Another fixed slit is shown between quadrants Q1 and Q2. The figure also shows inoperable shutters in grey that have been compiled from the most recent shutter operability data. Hovering the mouse over a single micro-shutter provides its position in the MSA and its state (commanded open or closed, stuck open or closed, etc.) This can be seen in the figure, where the text in the upper left of the window indicates that shutter "q3d300s6 is STUCK_CLOSED". This is quadrant 3, shutter 300 in dispersion and shutter 6 in the spatial direction.

The parent Catalog and Candidate Lists may be over-plotted by selecting one or more of them from the list below the MSA Shutter View. To remove a list, just click the button again to unselect it. Note that all sources from the added lists appear as black square symbols in the MSA Configuration Editor, to distinguish them from the planned sources which are shown as colored dots. The dot colors are green=Primary, blue=Filler, and black=Contaminant. Masked regions around each planned source are shown in light orange. The extent of these regions will depend on the planning parameters selected. Opening another shutter in these regions will cause a conflict since the spectra from the new shutter will overlap with that of another source. When this happens, conflicts are indicated in light magenta (see Figure 4). Failed open shutters are shown as single red shutters scattered around the MSA with their own light red masked regions (see Figure 3). Areas shown in white on the MSA Shutter View are areas that are not used in the MSA Configuration.

The configuration of shutters in the 4 MSA quadrants is shown, using the color convention described above in this article. Observed sources are plotted as round dots with colors: green = **Primary**, blue = **Filler**, and black = **Contaminant**. The same configuration may apply to a set of nodded exposures, but the positions of the sources within the view will depend on the nod position. The Catalog and any *Candidate Lists* defined from it can be over-plotted. In that case, unobserved sources are plotted as black squares (not shown in this example).

Zooming

It is possible to zoom in to view individual shutters in the MSA Configuration Editor, as shown in Figure 3.

Zooming in to shutter level is accomplished by clicking the right mouse button and dragging downward. This is usually enabled on a trackpad by using two fingers at once and dragging in an upward motion. Use a downward motion to zoom back out. A scroll action with the mouse can be used on some platforms. Using the arrow keys to zoom in and out is yet another option that works on some platforms. On a Mac, there are keystrokes that can be used for zooming: Command-"+" to zoom in, Command-"-" to zoom out, and Command-"0" to reset or reset the display.

Manipulating the shutters

The MSA Configuration Editor can be used to exchange planned sources for other Catalog sources. To do this, one would close the shutters of planned sources that are not wanted, and open shutters that correspond to preferred sources of interest, as shown in Figure 3. Individual operable shutters may be commanded opened or closed with a "left click" on the mouse or trackpad. Inoperable shutters (failed-closed shutters, shorted rows and columns) shown in grey cannot be planned open on sources or background. Note that when panning and zooming it is easily possible to open a shutter unintentionally. If that happens in an area masked by another source, the conflict area will be marked in light magenta as shown in Figure 4, making it obvious that there was an error. This is easily resolved by locating the new open shutter and toggling it off again before saving the configuration. If the new shutter happened to be in a location that is not in conflict with any planned sources, and the edited configuration is saved, the shutter will be opened during the observation. If there is a Catalog source present in the open shutter, it will be assigned to the new open shutter or "slit" and the resulting spectral data. If not, a fake source will be generated by APT and associated with the slit to prevent a failure in the pipeline processing of the data.

The Open all and Close all buttons can be used to open or close all the operable shutters in the MSA. These buttons should not be used when simply modifying an existing MSA Configuration to swap out a few sources. They can take a long time to complete. They have been provided for creating specialized MSA Configurations for use with protected target acquisition, or for the creation of exposures for MSA leakage calibration.

There is also a shortcut to make a long slit configuration: point the mouse at a column of shutters, and use Option + Left-Click (or Alt + Left-Click) to open (or close) the column of shutters. This operation may take a few seconds to display. However, built-in long-slits have been provided in the MSA Configuration pull-down menu within the observation template for convenience, so it should not usually be necessary to make one with the MSA Configuration Editor.

Details of the editing process using the MSA Configuration Editor. In this example, one planned **Filler** source was exchanged for an unplanned **Primary** source in the ***MSA Configuration***. These are the steps that were followed:
The primary **Candidate List** (highlighted in blue) was first over-plotted on the existing ***MSA Configuration*** by selecting it from the list shown below the MSA shutter area.
Then, the slit on one of the *Filler* sources (shown as a blue dot marked with a red circle) was closed by clicking on its shutters to shut them.
An alternate nearby source from the *Primary Candidate List* was then selected as the replacement.
A slit was created for the new source by opening 3 shutters around it (shown within the green circle).
When the edited configuration is saved, this new slit will be present in each exposure that uses this ***MSA Configuration***.
Note that the rows corresponding to the manually opened shutters will change from white to light orange to signify that they cannot accommodate any other sources without spectral overlaps.

In the MSA Configuration Editor, shutter conflicts from opening a shutter in the masked area of another planned source, or failed-open shutter in this case, result in the magenta conflict color. In the example shown here, the stuck open shutter indicated in red has an associated masked area shown in light red. When another shutter (shown in orange below and to the left of the failed-open shutter) is opened in the light red area, the conflicting mask region becomes colored light magenta. This example illustrates the difference between the light red (failed-open shutter), and magenta (conflict), mask colors.

Adding Master Background shutters

Instead of, or in addition to, altering the MSA Configuration to exchange planned sources, you may wish to simply add open shutters for the purpose of building a master background spectrum. Scattered shutters or slitlets can be opened in available areas of an MSA Configuration for this purpose, as described above. When the Master Background button is also enabled (bottom of Figure 5), the spectra from all shutters without planned sources (not including the background shutters in slitlets with sources) will be extracted and co-added in the pipeline to create a master background spectrum for subtraction from extracted target spectra. This applies to all exposures that use the same named configuration. For observations of moderately extended sources this may not be desirable, since the sources may occupy some of the shutters adjacent to the "target" shutters. In this case, the user would need to re-process the data so that the master background is made from just the scattered shutters and not those with sources in the slitlets.

When adding Master Background shutters, it is advised to overlay the entire Catalog on the MSA Shutter View (as shown in Figure 5) to confirm that there are indeed no other sources within the open shutters that may contaminate the master background spectrum.

In the MSA Configuration Editor a user may elect to add master background shutters. Check the **Master Background** checkbox, then click on non-conflicted shutters in the ***MSA configuration***. Make sure there are no other Catalog sources in the background shutters.

Export and import of MSA Configurations

There are buttons below the MSA Shutter View area of the MSA Configuration Editor to export and import MSA Configurations as CSV files. These are shown in Figure 5. The export and import options are intended for expert users who wish to manipulate MSA configurations outside of APT. Source positions at the MSA must be corrected for instrument and telescope geometric distortions, which require special tools. These buttons are not needed for editing an existing MSA Configuration, but are treated here for completeness. Users wishing to create MSA Configurations outside of MPT must do so at their own risk.

An MSA Configuration can be exported using the Export to CSV button. Export to CSV produces an ASCII file of comma-separated values that can be shared and imported into the MSA Configuration Editor with Import CSV. The exported CSV file has values of '0', '1', 's', or 'x' for each commanded open, commanded closed, failed-open, or failed-closed shutter, respectively.

Batch import of pre-existing CSV format MSA Configurations is also possible from the observation template using the Import Configuration(s) button beneath the Configurations/Pointings table. This feature allows sharing of MSA Configurations between members of an observing team. Expert users who may have tools to create or modify MSA Configurations outside of APT can use this feature to import them into an observation. Additionally, entire MPT Plans and APT programs themselves can be exported from the Plans tab of MPT. This capability is convenient for sharing between team members, as all of the Plan information is kept together. It is also possible to export the MSA target information as an ASCII file. To do this, select File → Export→ MSA Target Info in the main menu bar of the APT GUI found at the top of the screen when APT is active. The exported MSA Target Info file can be examined outside of APT. This format is more accessible and useful for tracking observed target information in an observation.

Sending shutters to Aladin

The Send Shutters to Aladin button below the display area in the MSA Configuration Editor can be used to view the MSA shutter configuration in Aladin. The shutters can be displayed overlaying an image of the field, to see where they will fall with respect to the sources. A NIRCam pre-image is the best option, when available, since the alignment between NIRCam and NIRSpec will be checked and updated soon after launch. Other images can be loaded from the MAST Archive to Aladin for display. For an example, see Figure 6.

Aladin image display with MSA shutters from a NIRSpec MOS exposure overlaid onto an HST Wide Field Camera image.

Additional fields in the MSA Configuration Editor

Note that there are several configuration-related fields at the bottom of the MSA Configuration Editor window (Figures 2 through 5). Though the following fields may not be useful in the workflow we are describing here, they are provided to present a complete description of the MSA Configuration Editor in one place, before moving on to our second workflow. The fields are Configuration Name, Base Pointing, Dispersion Offset, Spatial Offset, and a Master Background button.

Configuration Name
The MSA Configuration Name can be assigned using this field in the MSA Configuration Editor.

Base Pointing
Base Pointing equatorial coordinates RA and Dec values are also shown. The Base Pointing contains the sky coordinates for the MSA center (the reference position of the MSA aperture). Since the Base Pointing coordinates are within the Catalog area, the source positions from the Catalog will also appear in the MSA Shutter View. Note that in the workflow we are discussing here, the Base Pointing is greyed out and is un-editable. That is because the MSA Configuration comes from a Plan made in MPT, and altering it would invalidate the MSA Configuration that was designed to observe a set of sources in small slitlets at a fixed angle.

Dispersion Offset and Cross-Dispersion (Spatial) Offset
It is possible to apply pointing offsets to an MSA Configuration using the fields Dispersion Offset and Cross-Dispersion Offset. The offsets are in units of fractional shutters. This option is useful when designing extra exposures with small spatial or dispersion offsets in custom MOS Observations designed without the use of the automatic MPT Planner. Designing entirely new MSA configurations from scratch is described later in this article.

Master Background Button
Checking the Master Background button will allow the user to add extra shutters solely for the purpose of obtaining spectra that will be combined by the pipeline into a master background spectrum for background removal from source spectra. The Master Background button and its use are described in the section above on Adding Master Background shutters.

The Collapsed Shutter View

The planned sources may be examined in the Collapsed Shutter View (Figure 7) which is obtained by clicking on the Collapsed Shutters icon on the left panel in the MSA Configuration Editor. This view shows each target's position in its own shutter, all plotted together in a single virtual shutter. MSA bars are shown in grey, and the open area of the shutter is the yellow area. The Source Centering Constraint shown with a dashed white line should be the one used in the MPT Plan from which the MSA Configuration was made. These shutter constraints are described in the NIRSpec MPT - Planner. This view is useful for checking if any of the replacement sources in our newly edited MSA Configuration fall outside the original margin of interest.

Saving changes to the MSA Configuration

If desired, a new name can be given to the modified MSA Configuration in the Configuration Name field. To confirm and accept this new MSA Configuration, click the Save button at the bottom right of the MSA Configuration Editor window. This will produce a pop-up window as shown in Figure 8. Three options are provided: an option to save any changes made to the exposure + nod set (using the Create button), or to all shared instances of that named configuration within the observation (Update button), and a Cancel button to exit without any changes to the MSA Configuration. After making a selection, the MSA Configuration Editor will be closed and you will return to the view of the observation in APT, shown in Figure 1.

Pop-up window showing the 2 different save options, and an option to cancel. The option to **Update** the configuration for all exposures that use it, or to **Create** a new configuration for use on the exposure loaded into the MSA Configuration Editor is offered.

Creating a MOS Observation using a custom-made MSA Configuration

The MSA Configuration Editor also provides a means to create an MSA Configuration from scratch at the observation level in APT, and to apply it directly to a MOS observation. Caution: This workflow is tedious, especially when a Catalog of sources is used. It is almost always preferable to use MPT for planning an MSA Configuration of more than a handful of sources in a Catalog. An initial MSA Configuration designed with MPT can be altered in the MSA Configuration Editor. In the workflow below, the MSA Planning Tool is not used. A custom MSA Configuration will be designed entirely manually with the MSA Configuration Editor using an existing MSA Catalog Target from the Targets Folder.

In the Observation Folder:

Make sure you are in the Form Editor by clicking the Form Editor icon in the APT tool bar. Highlight the Observation Folder in the APT tree on the left. Create a new Observation in the Observation Folder.

In the Observation template :

Give the Observation a Label. Select the NIRSPEC Instrument, and NIRSpec MultiObject Spectroscopy template.
In the pull-down list for the Target, select the MSA Catalog Target that will be used. For MOS observations using a Catalog, the MSATA target acquisition methodology is required. (WATA is disabled when a Catalog target is chosen.)
Select the Primary and an optional Filler Candidate List. These lists are more meaningful for automatically-designed MOS observations using the MPT, which uses them to determine the best pointing. They can also be useful for creating custom configurations from scratch. Otherwise, select the parent Catalog as the primary sources and leave the Filler Candidate List unspecified.
Select a provisional Aperture PA (APA) for which you will design the example MSA Configuration. The APA is 138.5 degrees greater than the V3PA. (Unless a well-justified APT Special Requirement is added to the observation to constrain the APA, any APA will be assigned for planning the final program update.)
The Science Aperture is the MSA center. It is in the Science Parameters section shown in Figure 9. This is the reference point fo the pointing that will be specified below. When using a Catalog, this field will be greyed out to indicate that no other options are possible.
Click the Add button below the Exposure Specification table to add a first entry.
Specify the parameters for the Exposure Specification (Grating/Filter, Readout Pattern, Groups/Int, Integrations/Exp, etc.) using parameters determined using the ETC.
Add more exposure table entries, if desired. Note that there are buttons to Duplicate, Insert Above, and Remove exposure specifications in the table. There are also arrow buttons to the left of the table to move entries above or below other entries. To do this, an entry must first be highlighted by clicking the first column of an entry that you wish to move.
Click the Add button below the Configurations and Pointings table to add a new entry to this lower table.
Leave the MSA configuration unselected at this time. It will be specified in the MSA Configuration Editor.
Select a Grating/Filter pair from the pull-down menu in the column marked "Exposure Specification". Only those grating-filter pairs that are specified in the Exposure Specification table are offered in the pull-down menu. At this point, the APT GUI should appear as shown in Figure 9.
If you intend to nod in the slitlets that you will be designing, specify a Nod Pattern from the pull-down menu. Keep in mind that the slitlets you design below will need to be long enough to accommodate the nods that are specified here.
For the Pointing column, either copy and paste the base pointing from the MSA Catalog Target, or specify a preferred pointing from examining the field in Aladin. Small offset positions can be specified later using the MSA Configuration Editor.
Note that whenever you return from Aladin to the observation template, you will need to click the Form Editor icon.
Leave the Dispersion Offset and Cross-dispersion Offset columns empty for now. These are here to make it possible to more easily create a set of dithered exposures all referenced to a single base pointing.
Click the Edit button in the column labeled "Edit Config" to open the MSA Configuration Editor. A new pop-up window will appear.

In the MSA Configuration Editor pop-up:
Overlay the source Catalog or Candidate List of interest by clicking the appropriate checkbox below the shutter view.
Adjust the preferred central pointing for the MSA Configuration, if desired, by specifying dispersion or cross-dispersion offsets. The base pointing of an MSA Catalog Target should not be changed.
Open shutters in the MSA Shutter View by clicking on them, as described in the section above on manipulating shutters to form slitlets on sources.
When done, give the configuration a new Configuration Name in the MSA Configuration Editor.
Click Save to return to the Observation template. You will get a pop-up with an option to create a new configuration or update the config. Select the former.

Back at the Observation Template level:
Specify any remaining parameters that you may have skipped for this exposure, like the Nod Pattern. Selecting the 3-shutter nod pattern will create the exposures for the nods. The spatial offsets required for the nods will be automatically added.
You may add other exposures for the observation in the Configurations/Pointings table or define a new grating/filter exposure in the Exposure Specification table. You can Add, Duplicate, Insert Above, and Remove entries using the buttons below the tables. Note that the table displays a few additional columns: Nod Pattern, Total Integrations, which is just the number of integrations in the Exposure Specification entry times the number of nods (in the Nod Pattern), and finally the Total Exposure Time for the exposure(s) on each line.

Detailed view of the MOS Observation template in APT. The MSA Configuration Editor pop-up window is initiated by clicking **Edit** at the end of a row in the **Configurations/Pointings** table.

Examining a custom MOS Observation in MPT

See Also: NIRSpec MPT - Plans

In this article we described how to modify an MPT-generated MOS observation, or create a custom MOS observation using the MSA Configuration Editor. A custom MOS observation created as described above can also be examined with the MPT tools in the Plans pane of MPT, and compared with any MPT-generated Plan there. There are 2 ways to do this: once a MOS observation has been created in the MOS observation template in the Form Editor of APT, click the Review in MPT button at the bottom of the Science Parameters section of the observation template. Alternatively, one may highlight the observation in the APT tree, and then open up the MPT by clicking on the icon in the toolbar of APT. Once in MPT, open the Plans tab and the new observation should appear as a new Plan in the plan summary area. If there are any MPT-generated Plans in the APT program, the new observation will appear at the top of the list. Refer to the article NIRSpec MPT - Plans to learn how to interact with and interpret the information presented in this view. One may switch to a different MOS observation in the APT program by simply highlighting it in the tree editor while remaining in the MPT Plans pane. Only one MOS observation at a time can be compared to the set of MPT-generated Plans.

Note that when highlighting a MOS observation created from an MPT Plan, there may be additional Contaminants noted in the observation. This happens because MPT only notes Primary and Filler sources that are Contaminants, while the Plan made from the observation includes additional sources coming from the parent Catalog.

It is not only possible to examine custom MOS observations in MPT in this way, but it is also possible to create a new observation from the merger of 2 or more Plans in MPT, even if one of those plans originated from a custom-designed MOS observation. Plan merging can only be done when the plans have been derived from the same parent Catalog, and use the same Aperture Position Angle. Plan merging into a single observation can help to save visit overheads, like GS acquisition in many cases.

References

Karakla, D. et al. 2014, Proc. SPIE 9149
The NIRSpec MSA Planning Tool for multi-object spectroscopy with JWST

Latest updates

02 Apr 2021
Added figure for master background shutters and changed figure of shutters in Aladin.
04 Aug 2020
Added Fig 4 and notes about open shutter conflicts, and the handling of empty slits in DMS processing in a few sections. Reorganized a section to improve clarity.
02 Jul 2020
Updated Figs 1 and 8 for Assigned APA
22 Jun 2020
Added new section describing how to examine a MOS observation in MPT.
17 Feb 2020
Replaced Fig 1 and updated discussion of Nod Pattern
19 Jan 2020
Modified for new MPT in APT 2020.1.1

Originally published

12 Jun 2017

JWST User Documentation

Custom MOS Observations using the MSA Configuration Editor