- JWST Cycle 1 Proposal Opportunities
- James Webb Space Telescope Call for Proposals for Cycle 1
- •JWST Cycle 1 Proposal Checklist and Resources
- •JWST Cycle 1 Proposal Policies and Funding Support
- JWST Cycle 1 Proposal Categories
- •JWST Cycle 1 Observation Types and Restrictions
- •JWST Cycle 1 Proposal Preparation
- •JWST Cycle 1 Single-Stream Proposal Process
- •JWST Cycle 1 Special Submission Requirements
- •JWST Cycle 1 Observation Mode Restrictions
- •JWST Cycle 1 Proposal Selection Process
- •JWST Cycle 1 Awarded Program Implementation
- •JWST Cycle 1 Proposal Science Categories and Keywords
- JWST Director's Discretionary Early Release Science Call for Proposals
- •JWST DD ERS Notice of Intent to Propose
- •JWST DD ERS Proposal Checklist
- •JWST DD ERS Program Goals, Project Updates, and Status Reviews
- •JWST DD ERS Proposal Policies
- •JWST DD ERS Preparatory Funding Budget Requirements
- •JWST DD ERS Funding and Institutional Endorsement
- •JWST DD ERS Observation Types and Restrictions
- •JWST DD ERS Special Observational Policies
- •JWST DD ERS Special Submission Requirements
- •JWST DD ERS Proposal Process
- •JWST DD ERS Proposal Preparation
- •JWST DD ERS Proposal Evaluation and Selection Procedures
- •JWST DD ERS Proposal Science Categories and Keywords
- JWST Cycle 1 Guaranteed Time Observations Call for Proposals
- •JWST Cycle 1 GTO Proposal Submission Policies
- •JWST Cycle 1 GTO Proposal Submission Process
- •JWST Cycle 2 and 3 GTO Proposal Process
- JWST GTO Observation Specifications
- James Webb Space Telescope Call for Proposals for Cycle 1
- JWST General Science Policies
- • JWST Observing Overheads and Time Accounting Policy
- • JWST Duplicate Observations Policy
- • JWST Science Parallel Observation Policies and Guidelines
- • JWST Observing Program Modification Policy
- • Policies for the Telescope Time Review Board
- • JWST Target of Opportunity Program Activation
- NASA-SMD Policies and Guidelines for the Operations of JWST at STScI
- •Policy 1 - Limitations on the Use of Funds for the Research of General Observers and Archival Research
- •Policy 2 - Data Rights and Data Dissemination
- •Policy 3 - Data Requests and Facilities
- •Policy 4 - Post-Launch Commissioning of JWST
- •Policy 5 - Clarification of Extensions of Exclusive Access Data to Public Affairs Activities
- •Policy 6 - Distribution of JWST Science Data Obtained from Investigations Other Than Those Selected Through the Peer-review Process
- •Policy 7 - NASA Needs for Support for Other Missions
- •Policy 8 - Definition of Observing Time
- •Policy 9 - Allocation of Guaranteed Observing Time to Scientists Selected Under AO 01-OSS-05 and Through NASA-ESA-CSA Agreements
- •Policy 10 - Redistribution of Guaranteed Observing Time Among Observers
- •Policy 11 - Protection of Science Programs Associated With Guaranteed Time
- •Policy 12 - Education and Public Outreach
- Methods and Roadmaps
- JWST Imaging
- • JWST Slit Spectroscopy
- • JWST Slitless Spectroscopy
- JWST High-Contrast Imaging
- •Contrast Considerations for JWST High-Contrast Imaging
- •JWST Coronagraphic Observation Planning
- •JWST Coronagraphic Sequences
- •JWST Coronagraphy in ETC
- •JWST High-Contrast Imaging in APT
- •JWST High-Contrast Imaging Inner Working Angle
- •JWST High-Contrast Imaging Optics
- •JWST Small Grid Dither Technique
- •MIRI-Specific Treatment of Limiting Contrast
- •NIRCam-Specific Treatment of Limiting Contrast
- •NIRISS AMI-Specific Treatment of Limiting Contrast
- •Selecting Suitable PSF Reference Stars for JWST High-Contrast Imaging
- JWST Integral Field Spectroscopy
- JWST MOS Spectroscopy
- JWST Time-Series Observations
- •Overview of Time-Series Observation (TSO) Modes
- •Noise Sources for Time-Series Observations
- •Sensitivity of Time-Series Observation Modes
- •Bright limits of Time-Series Observation Modes
- •Preparing Time-Series Observations with JWST
- •Target Acquisition for Time-Series Observations
- •NIRCam-Specific Time-Series Observations
- •NIRISS-Specific Time-Series Observations
- •MIRI-Specific Time-Series Observations
- JWST Moving Target Observations
- •Field of Regard Considerations for Moving Targets
- •Instrument-Specific Considerations for Moving Targets
- •JWST Moving Target Calibration and Processing
- •JWST Moving Target Ephemerides
- •JWST Moving Target Observing Procedures
- •JWST Moving Target Policies
- JWST Moving Targets in APT
- •JWST Moving Targets in ETC
- •JWST Moving Target Useful References and Links
- •Overheads for Moving Targets
- •Moving Target Recommended Strategies
- JWST Parallel Observations
- • JWST Target of Opportunity Observations
- • General Proposal Planning Workflow
- Observatory Functionality
- • JWST Position Angles, Ranges, and Offsets
- • JWST Instrument Ideal Coordinate Systems
- JWST Background Model
- • JWST Guide Stars
- • JWST Mosaic Overview
- • JWST Dithering Overview
- JWST Duplication Checking
- JWST Observing Overheads and Time Accounting Overview
- •JWST Observing Overheads Summary
- •JWST Slew Times and Overheads
- JWST Instrument Overheads
- Observing Overheads for NIRCam Imaging
- • JWST Data Rate and Data Volume Limits
- Observatory Hardware
- • JWST Observatory Overview
- • JWST Observatory Coordinate System and Field of Regard
- • JWST Field of View
- • JWST Orbit
- JWST Spacecraft Bus
- • JWST Pointing Performance
- • JWST Telescope
- • JWST Wavefront Sensing and Control
- • JWST Momentum Management
- • JWST Integrated Science Instrument Module
- • JWST Solid State Recorder
- • JWST Target Viewing Constraints
- • Fine Guidance Sensor, FGS
- Exposure Time Calculator
- • JWST Exposure Time Calculator Overview
- • JWST ETC New User Guide
- • JWST ETC Calculations Page Overview
- • JWST ETC Scenes and Sources Page Overview
- • JWST ETC Downloads
- • JWST ETC Creating a New Calculation
- • JWST ETC Defining a New Scene
- • JWST ETC Defining a New Source
- • JWST ETC Sharing Workbooks
- • JWST ETC Using the Sample Workbooks
- • JWST ETC Source Spectral Energy Distributions
- • JWST ETC User Supplied Spectra
- • JWST ETC Batch Expansions
- JWST ETC Strategies
- • JWST ETC Backgrounds
- JWST ETC Target Acquisition
- • Residual Flat Field Errors in the ETC
- JWST ETC Pandeia Engine Tutorial
- • JWST ETC Images and Plots
- • JWST ETC Reports
- • JWST ETC Point Spread Functions
- • JWST ETC Wavelength of Slice
- • JWST ETC Instrument Throughputs
- • JWST ETC Defining an Extended Source
- Astronomers Proposal Tool
- • JWST Astronomers Proposal Tool Overview
- • APT Proposal Information
- APT Targets
- • APT Observations
- • APT Visit Splitting
- JWST APT Coordinated Parallel Observations
- • JWST APT Pure Parallel Observations
- • APT Target Acquisition
- JWST APT Mosaic Planning
- • APT Special Requirements
- • APT Visit Planner
- • JWST APT Aladin Viewer
- • APT Smart Accounting
- • JWST APT Target Confirmation Charts
- • APT Submitting Your JWST Proposal
- JWST APT Functionality Examples
- • JWST APT Help Features
- • JWST APT Training Examples and Video Tutorials
- Other Tools
- Mid Infrared Instrument
- • MIRI Overview
- MIRI Observing Modes
- MIRI Instrumentation
- MIRI Operations
- MIRI Target Acquisitions
- MIRI Dithering
- MIRI Mosaics
- •MIRI MRS Simultaneous Imaging
- MIRI Time Series Observations
- MIRI Predicted Performance
- MIRI APT Templates
- MIRI Observing Strategies
- MIRI Example Programs
- •MIRI Coronagraphy of GJ 758 b
- MIRI and NIRSpec Observations of SN1987A
- •MIRI and NIRCam Coronagraphy of the Debris Disk Archetype around Beta Pictoris
- •MIRI IFU and NIRSpec Observations of Cas A
- Near Infrared Camera
- • NIRCam Overview
- NIRCam Observing Modes
- NIRCam Instrumentation
- •NIRCam Field of View
- •NIRCam Modules
- •NIRCam Optics
- •NIRCam Dichroics
- •NIRCam Pupil and Filter Wheels
- •NIRCam Filters
- •NIRCam Coronagraphic Occulting Masks and Lyot Stops
- •NIRCam Filters for Coronagraphy
- •NIRCam Grisms
- •NIRCam Weak Lenses
- NIRCam Detectors
- NIRCam Operations
- NIRCam Dithers and Mosaics
- •NIRCam Coronagraphic PSF Estimation
- •NIRCam Coronagraph Astrometric Confirmation Images
- •NIRCam Apertures
- NIRCam Target Acquisition Overview
- NIRCam Predicted Performance
- NIRCam APT Templates
- NIRCam Observing Strategies
- NIRCam Example Programs
- NIRCam Imaging and NIRISS WFSS of Galaxies Within Lensing Clusters
- •NIRCam Coronagraphy of HR8799 b
- •NIRCam Deep Field Imaging
- NIRCam Grism Time-Series Observations of GJ 436b
- NIRCam Time-Series Imaging of HAT-P-18 b
- •NIRCam WFSS Deep Galaxy Observations
- •NIRCam and MIRI Coronagraphy of the Debris Disk Archetype around Beta Pictoris
- Near Infrared Imager and Slitless Spectrograph
- • NIRISS Overview
- NIRISS Observing Modes
- NIRISS Instrumentation
- NIRISS Operations
- NIRISS Predicted Performance
- NIRISS APT Templates
- NIRISS Observing Strategies
- NIRISS Example Programs
- NIRISS WFSS and NIRCam Imaging of Galaxies Within Lensing Clusters
- NIRISS AMI Observations of Extrasolar Planets Around a Host Star
- NIRISS SOSS Time-Series Observations of HAT-P-1
- Near Infrared Spectrograph
- NIRSpec Overview
- NIRSpec Observing Modes
- NIRSpec Instrumentation
- •NIRSpec Optics
- •NIRSpec Dispersers and Filters
- NIRSpec Detectors
- •NIRSpec Micro-Shutter Assembly
- •NIRSpec Integral Field Unit
- •NIRSpec Fixed Slits
- NIRSpec Operations
- NIRSpec Dithers and Nods
- NIRSpec MOS Operations
- NIRSpec IFU Operations
- •NIRSpec FS Operations
- •NIRSpec BOTS Operations
- NIRSpec Target Acquisition
- NIRSpec Predicted Performance
- NIRSpec APT Templates
- NIRSpec Multi-Object Spectroscopy APT Template
- •NIRSpec MOS Proposal Checklist
- •NIRSpec MSA Planning Tool, MPT
- NIRSpec MPT - Catalogs
- •NIRSpec MPT - Planner
- NIRSpec MPT - Manual Planner
- •NIRSpec MPT - Plans
- •NIRSpec MPT - Parameter Space
- •NIRSpec MSA Spectral Visualization Tool Help
- •NIRSpec Observation Visualization Tool Help
- •NIRSpec IFU Spectroscopy APT Template
- •NIRSpec Fixed Slit Spectroscopy APT Template
- •NIRSpec Bright Object Time-Series APT Template
- •NIRSpec FS and IFU Mosaic APT Guide
- NIRSpec Multi-Object Spectroscopy APT Template
- NIRSpec Observing Strategies
- •NIRSpec Background Recommended Strategies
- •NIRSpec Bright Spoilers and the IFU Recommended Strategies
- •NIRSpec Detector Recommended Strategies
- •NIRSpec Dithering Recommended Strategies
- •NIRSpec MOS Recommended Strategies
- •NIRSpec MSA Leakage Subtraction Recommended Strategies
- •NIRSpec Target Acquisition Recommended Strategies
- NIRSpec Example Programs
- NIRSpec and MIRI Observations of SN1987A
- •NIRSpec and MIRI IFU Observations of Cas A
- NIRSpec Bright Object Time Series Observations of GJ 1214b
- NIRSpec MOS Deep Extragalactic Survey
- •NIRSpec MOS Observations of NGC 346
- Understanding Data Files
- Obtaining Data
- Data Processing and Calibration Files
- JWST Data Reduction Pipeline
- • Primer and Tutorials
- • Pipeline User's Guide
- • Software Reference Documentation
- Algorithm Documentation
- • Obtaining and Installing Software
The JWST MSA Planning Tool main interface is presented and described in detail. All steps to create a plan containing targets, slitlet structure, dithering strategies, and exposure configuration are discussed.
The NIRSpec MSA Planning Tool (MPT) is the official software tool to design a NIRSpec MOS observation. The main purpose of MPT is to optimally plan micro-shutter assembly (MSA) observations, given source positions and the limitations of the MSA. Constraints, such as the bars in between shutters and the inoperable shutters, are fully accounted for in MPT. MPT contains the precise coordinate transformation between the MSA plane and the sky plane, taking into account the distortion of the combined optical path of the telescope and NIRSpec optics.
This page contains information on the MPT Planner area, including:
- An Overview of the MPT Planner
- The MPT Planner area has 7 sections that we describe in detail below.
An overview of the MPT Planner
The purpose of the MPT Planner1 is to allow the user to define parameters that are the input of the algorithms that produce the final pointings, MSA configurations, and target sets. An "MSA configuration" is defined as a set of open and closed micro shutters in the MSA. Once a set of Planner parameters are defined, a Plan can be generated. Observers can generate several Plans which are saved when they save their APT file. After assessing the quality of individual Plans, the user can then select one or more Plans from which observations will be made. When an observation is generated, see NIRSpec MPT - Plans, the observation template in APT is automatically completed for the user. One Plan in the MPT Planner is used to create one observation in APT.
For MPT to work, the user must be connected to the internet so MPT can check whether an aperture position angle is feasible when the user begins to create a plan.
The appropriate selection of the Planner parameters discussed throughout this article depends on science goals. Consult NIRSpec MOS Recommended Strategies for further advice. For examples of how the choices below affect the results of the Planner, see the Parameter Space article. Parameters and their values are designated using bold font italics throughout this article.
After having ingested a Catalog with sources of interest and creating a Primary candidate set (and a Filler candidate set, if desired), the user should move on to the Planner tab in the MSA Planning Tool. The Planner is shown in Figure 1.
Reminder: If you are not seeing the MPT, make sure you are in the Form Editor view (click the top left button in the APT GUI window), and that you have highlighted the Observation Folder in the tree on the left side of the APT GUI window.
NIRSpec MPT: Planner, Video 1: Aperture PA and Candidate Lists
The MPT Planner is designed to automatically create optimal plans but it is also possible for the user to create plans manually by selecting a pointing and clicking MSA shutters open and closed. Checking the Manual Planning checkbox at the top of the window puts the planner into the manual planning view. For information about the fields shown in this view see NIRSpec MPT - Manual Planner.
MPT Section 1: Planning Angles
Aperture PA (APA)
A given NIRSpec MSA observation must be executed at a specific telescope orientation angle so that the selected sources will fall into the open shutters as planned. Because of the telescope's orbital position and sunshield constraints, a given orientation may only be possible for limited periods during the year or not available at all. The Target Visibility Tools can be used to determine the range of feasible orientation angles for a target throughout the telescope's orbital cycle.
For most NIRSpec MOS observations, it is recommended to experiment with several different feasible Aperture Position Angles prior to initial proposal submission. The submitted APA is used to create place-holder or "planning visits" with MPT. Once a proposal is accepted, it will be assigned a fixed orientation and a corresponding window of time when observations will be made.
For proposal submission, use any feasible APA from the orientation angles provided by the JWST Target Visibility Tool for the time of observation. For final program submission, use the fixed orientation APA that has been assigned to your observation by the schedulers at STScI. This assigned angle will correspond to one or more plan windows for execution in the scheduling timeline.
The APA (an angle between 0 and 360 degrees) specifies the orientation of the cross-dispersion axis of the MSA aperture measured from North in the counterclockwise direction. Figure 2 shows how this angle is measured on the sky. The "Y" axis represents the cross-dispersion direction of the MSA.
Programs that have an orientation or timing special requirement added to the observation can restrict scheduling opportunities. Most NIRSpec MOS programs should be submitted without added orientation restrictions, in order to allow the schedulers to find suitable windows for them. Also, when the proposal is submitted, the observer should explicitly add an "ON HOLD for aperture position angle assignment" special requirement to their NIRSpec spectroscopy observations.
True angle to target
The True angle to target field appears in the Planner, but is greyed out and cannot be changed by the user. This is the angle between the telescope's velocity vector at the center of the planning window and the telescope pointing. It is used to make small corrections to source positions at the MSA resulting from the velocity of the spacecraft.
The True angle to target offers a quick way to check target visibility: its value will not update if the selected APA is not feasible.
MPT Section 2: Candidate lists
The MPT is designed to create plans that use two levels of priority for science sources: a "Primary" candidate list, and a "Filler" candidate list. These lists are created from the input Catalog that was uploaded following the instructions in the article NIRSpec MPT - Catalogs.
The tool will attempt to maximize the number or the summed weight of Primary sources in the configurations it derives. Therefore, these sources will directly influence the pointing selection for both fixed and dithered observations. The Primary candidate list is required to generate a plan in MPT. At the derived best pointings, MPT will use the (optional) Filler candidate list to fill available areas in the MSA configuration, to observe more sources in each exposure. There is no attempt by the algorithms to complete the sources from the Filler list (i.e. to observe them through all dithers) in the same way that the primary sources are completed. Fillers do not define the pointings, they are only selected to maximize MSA usage. Only the Primary candidate sets determine the selected pointings.
Observers should be aware that they should have all sources of interest in a single parent catalog for a given observation or a set of observations. The candidate lists (Primary Candidate List and Filler Candidate List) are derived from this single Catalog. Using Primary candidates from one Catalog and Fillers from a different parent Catalog will cause save errors in APT. Users will not be able to make observations from Plans made with candidate lists derived from different Catalogs.
MPT Section 3: Slit Setup
In this section the user defines the shape of the slitlet and the Source Centering Constraint.
NIRSpec MPT: Planner, Video 2: Slit and Dither Setup
The NIRSpec MSA is composed of ~250,000 micro shutters. By commanding open micro shutters, it is possible to create longer slits (in the cross-dispersion direction only) which are referred to as "slitlets". There are four selectable Slitlets of differing length, and their structure depends on the number of adjacent micro shutters that are open: 1, 2, 3, or 5. The spectrum from a slitlet will be segmented, with bar shadows between the individual shutters making up the slitlet.
Only one default Slitlet shape and Source Centering Constraint (see below) may be selected for a given plan. Each selected target in a Plan will be observed with the same slitlet shape using the same source centering constraint in an Observation designed with MPT. Currently there is no mechanism in MPT to append a new set of targets to existing MSA configurations using a different slit shape or centering constraint.
Slitlets of any size may be created, modified, or deleted using the Manual Planner. The Manual Planner can be used from scratch to design a custom MSA configuration with slits of different lengths for different size sources, however it is important to be careful about nodding in the slitlet when slit lengths differ in the same MSA configuration. It is also possible to pass MSA configurations designed with the automatic MPT planner to the Manual Planner for modification there.
The yellow and black sketch in the Planner, shown in Figure 3, illustrates the options for slitlet length. Yellow shutters are the open shutters.
Each open micro shutter, when projected onto the sky, has dimensions of only 0.2" in the dispersion direction by 0.46" in cross-dispersion. These are the internal (open) dimensions. Each shutter is bordered by a bar of width ~0.069", which vignettes a small area of the sky around it. In any given exposure, a particular source may fall anywhere inside a given shutter, or behind the bars. The position of the source with respect to the shutter will affect its observed flux.
Source Centering Constraint
The Source Centering Constraint in the Planner presents five increasingly limited choices for the shutter margin to constrain the positioning of the source within the shutter to help reduce slit losses. The larger the margin, the more limited the area available for centering the source. In general, larger margins result in fewer selected targets, although this effect depends strongly on the source density of the Primary candidate list.
The default constraint is the Entire Open Shutter Area. The figures in column two of Table 1 represent a single micro shutter. The yellow area represents the area available to a potential target corresponding to the indicated Source Centering Constraint. The exact dimensions of the constrained area are not precise, they are just suggestive. The actual applied source centering constraint can be seen as a dashed white line when viewing the "Collapsed Shutter View" in an MOS exposure.
To be included as a successful source in a plan, the source center must fall within the central area of the shutter defined by the specified margin. A more restrictive shutter margin will limit the photometric error, but may also cause the overall efficiency of the plan to drop. This parameter is relevant primarily for point sources, which can suffer from large photometric inaccuracies due to limitations in the pointing accuracy, especially if a source happens to be centered near the shutter edge where the throughput drops quickly. The shutter margin translates to a minimum possible slit transmission of a point source relative to a perfectly centered point source (column 3 of Table 1), anchored at 2.95 μm. Of course, the actual throughput will depend on the wavelength of the observation and the source shape (point vs. extended).
Users observing extended sources should avoid over-constraining the shutter margin since source centering is less critical, and it could decrease the overall number of targets observed per MSA configuration.
Table 1. Source centering options within an individual micro shutter.
Column two shows a sketch of the open micro shutter area (yellow area) for each margin; the black surface represents the margin.
|Source Centering Constraint||Figure||Minimum Relative Flux Transmission at 2.95 μm|
(sources can be behind the MSA bars)
Entire Open Shutter Area (default)
Table note: The size of the margins were updated in APT 25.4 and represent the most precise knowledge of the average shutter dimensions. The path losses at these margins are for a point source. They were measured at 2.95 μm, and are relative to a perfectly centered source. At larger wavelengths, the PSF is broader, and the overall slit loss is greater. The sketches shown in this table are representative only and may not reflect the actual sizes. The margins shown in the last column are measured from the mid-bar position inward, toward the center of the shutter.
As a result of the exceedingly small aperture size of a micro shutter, moderate flux can be lost outside of the slit. Slit losses depend not only on the location of the source in the slit, but also the wavelength, since the point spread function (PSF) increases with wavelength as shown in Figure 4. The "relative flux throughput" value in the table is the minimum percentage of flux at 2.95 μm that makes it through the MSA shutter, compared to a perfectly centered point source.
MPT Section 4: Dither Setup
In this section, the observer can define dither and nodding patterns for the observation. Most JWST observations will require dithering and NIRSpec users are encouraged to make use of this feature. Not only is dithering critical for improving the sampling, but it can help to estimate and remove light leakage through the MSA's finite contrast shutters in MOS mode. In this mode it is not easily possible to take leakcal exposures as are available in IFU mode. More information on the advantages of dithering can be found in the article NIRSpec MOS Dither and Nod Patterns.
The telescope can be repositioned slightly between exposures to place the targets into different shutters within their respective slitlets in an MSA configuration. This is called nodding. If nodding is selected (by clicking the checkbox Nod in Slitlet in the Planner), the same MSA configuration will be used to observe the target once in each open shutter in the slitlet.
When nodding is selected, the default pipeline will automatically perform a background subtraction using the various nod positions.
Note that this action increases the number of exposures. Generally, there will be one nod position per slitlet shutter. In the 5-shutter slitlet, there is also the possibility of only 3 exposures, with nod positions in the central, uppermost and lowest shutters only. This option, called exposures per configuration is visible only when the 5 Shutter Slitlet and the Nod in slitlet options are selected.
In addition to nodding, which moves the telescope very slightly, users are offered the ability to add larger, or primary, dithers. There are currently two different algorithms implemented within the MSA Planning Tool for deriving best pointings: Fixed Dithers and Flexible Dithers. Primary dithers that move the targets outside their respective slitlets from one exposure to the next will require a reconfiguration of the MSA in order to re-observe the same targets. The user must first choose a dither type (Fixed or Flexible). Fixed dithers are specified in units of integer shutters in the dispersion and spatial direction, and represent specific offsets to apply to the next pointing. Flexible dithers are specified in units of arcseconds in each direction, and these merely constrain the dithers in each direction by setting a minimum or maximum value.
For each new Fixed or Flexible Dither that is added, a new primary pointing will result, along with an associated MSA configuration. This will result in an additional exposure (or set of nodded exposures). The number of (MSA) configurations needed to execute the entire set of dithers is computed and displayed beneath the table of dithers shown in the GUI.
There are advantages and drawbacks to both of these algorithms, described below. Both Fixed and Flexible dither algorithms account for relative distortions between pointings, so each can handle dithers of any size.
Select this option if dithering is not desired. Note that dithering is highly recommended for JWST observations. More information on the advantages of dithering can be found in the article NIRSpec MOS Dither and Nod Patterns.
This dither pattern consists of offsets in the dispersion direction and/or in the cross-dispersion direction. There is no limit to the size of the dither that may be specified, but larger dithers may naturally result in some loss of targets that can be observed at both pointings simply due to diminished areal overlap of sources in the quadrants at very disparate pointings.
The Fixed Dither algorithm is also generally better at yielding many more completed sources (i.e. observed at all dither points) than the Flexible Dither algorithm described below. However, partially-observed sources are not included in the plan. For that reason, Fixed Dithers tends to yield fewer targets per MSA configuration. Adding Fillers helps to fill the MSA. Also, adding the Primary sources into the top of the Fillers list may help to produce observations of additional Primary sources. Optionally, the Manual Planner can be used after the fact to add in slitlets to the MSA configuration(s) designed with the MPT to observe additional sources.
To create a pattern, simply click the ADD button and define the offsets. Offsets are in units of micro shutters. Figure 5 shows the default parameter values when the window is opened for the first time.
By clicking on the Add Constraints button it is possible to define a new primary dither point in a flexible dither pattern.Constraints are defined based on the separation between pointings as shown in Figure 6. The user can define the distance between pointings in units of arcsec for both the dispersion and cross-dispersion directions. A set of default parameter values are shown in Figure 7.
For Flexible Dithers, multiple possible pointings are tested at each dither step, building families of possible solutions, and the best family is then chosen. These constraints may always be edited or removed if necessary, by using the Remove and Edit buttons in this section.
MPT Section 5: Exposure Setup
NIRSpec MPT: Planner, Video 3: Exposure Setup, Search Grid, and Parameters
In section 5 of Figure 1 the observer defines the exposure specification. In the table in this section, each new exposure specification results in one or more new exposures. The number of new exposures resulting from a single exposure specification (or, each row in this table) is determined by the dither pattern specified (see Section 4). Click the ADD button to add a new exposure. An exposure is configured by setting the Grating/Filter combination, the Readout Pattern, Number of Groups, and Number of Integrations, described in Table 2. The ETC uses these parameters as input and produces associated exposure times and signal-to-noise (SNR) estimates.
Users should ultimately use the Exposure Time Calculator for all sensitivity calculations.
Recommendations about exposure parameter selection are given in NIRSpec Detector Recommended Strategies.
Table 2: Description of Science Parameters for a given exposure
|Grating/Filter||Select a grating/filter combination from the pull down menu. The article NIRSpec Dispersers and Filters describes all the available combinations for NIRSpec observing modes.|
Each exposure consists of a set of one or more integrations. Integrations consists of a set of nondestructive reads of the detector.
The detectors can be read in different ways. The available patterns are NRS, NRSRAPID, NRSIRS2, and NRSIRS2RAPID. These patterns are described in full detail in the article NIRSpec Detector Readout Modes and Patterns. The default pattern is NRS, which will average 4 frames on board (i.e. there are 4 frames in one Group).
Select the pattern that best suits your observation.
The number of groups in an integration. The number of groups, together with the Readout Pattern (i.e. the number of frames in a group) will determine the length or duration of an integration, using the specified options for averaging or not averaging frames.
|Integrations/Exp||The number of integrations comprising an exposure, where an integration is defined as a set of non-destructive reads.|
|Autocal||This option is available to automatically add calibration exposures to a science exposure. For the MOS, the options are NONE, WAVECAL, FLAT, and BOTH. NONE is the default and is recommended.|
|ETC Wkbk.Calc ID||The user should enter the ETC calculation ID from the associated ETC Workbook. See note below.|
Exposures may be reorganized and removed if necessary, by using the Duplicate, Insert Above, and Delete buttons.
The ETC calculation ID from the associated ETC Workbook should be entered for each exposure in the exposure specification table before generating a Plan. There is currently no other way to add this information at a later stage. Its is expected this will be fixed in APT 27.2.
The main purpose of multi-object spectroscopy is to obtain the spectra of many sources simultaneously. The incoming light passes through a long pass filter before it goes through the slitlet in the MSA, and is dispersed by the chosen grating onto the detector. The MSA Planning Tool is designed to prevent spectra from overlapping on the detector, including second order spectra, typically allowing just one source per row for a given open shutter. This is certainly useful when dealing with high resolution gratings. However, in some limited science cases, overlapping spectra can be tolerated. The checkbox Multiple Sources per Row (as shown in Figure 8) is offered to optionally allow for overlap in these cases.
The behavior of the Multiple Sources Per Row option depends on the choice of dispersing element or elements. In the case where the Prism is used exclusively, the Multiple Sources Per Row option is not available. The Prism allows multiple sources per row by default because the spectra do not extend beyond ~500 pixels in the dispersion direction. In the case of a grating, or a grating plus the Prism in the same Plan, the behavior of the Multiple Sources Per Row checkbox is summarized in Table 3.
Table 3: Using the "Multiple Sources Per Row" Option
|Grating option||"Multiple Sources Per Row" Selected ?||Description|
|Any grating||Yes||High (R-2700) and medium (R-1000) resolution grating data are allowed to overlap spectrally. A separation as small as 4 shutters in dispersion is allowed. Spectra will overlap.|
|PRISM + grating(s)||No||Gratings drive the multiplexing and no spectra will overlap (including the short Prism spectra).|
|PRISM + grating(s)||Yes||The multiplexing will always be driven by the Prism. This will result in overlap of grating spectra if the Prism + gratings are planned together.|
Note that currently, the more efficient PRISM-style multiplexing described in the last row of the table above is not working in rows near failed open shutters, and is also not being applied to Fillers. These problems are expected be fixed in APT 27.0 or later.
MPT Section 6: Search Grid
Both Fixed and Flexible Dither algorithms (discussed above in section 4), start by constructing a grid of test pointings on the sky. The grid is aligned with the orientation of the dispersion and spatial axes of the MSA. For each point, the algorithms attempt to find the maximum number of high-priority sources that can be observed given the constraints of the MSA. As part of this process, the tool avoids inoperable shutters and will not allow overlapping spectra, unless specified.
The total number of observed sources, or the sum of their weights (if Weights are used in planning, see below) are tallied and saved at each test pointing. The result is called a "heat map". The heat map is used internally, but is not a delivered product.
Following the heat map creation, the two algorithms work differently to derive the best pointings on the sky. There are a few critical parameters in both algorithms that affect the computational time needed to create a plan. The size of the Primary Candidate List, the number of MSA configurations, and the number of grid points are the most relevant.
In this section of the MSA Planning Tool the user defines the size of the search grid, its Center, and the Search step size mentioned above as shown in Figure 9. The entire extent (Center RA and Dec, the Width and Height) of the input Catalog at the specified Aperture Position Angle is used to define the area over which test pointings are examined. The default value of Search Step Size is 30". If the default grid spacing value is changed, the tool will re-compute the number of grid points that will be searched, and will display the result next to the selected spacing as shown in Figure 9. Normally, reducing the step size will improve target numbers. Grid step sizes in the range of 2" - 12" give similar plan results in many fields, for typical source densities. Even reducing to a step size as small as 1/3 of a shutter width (~85 milli-arcsec) may provide improved results, but at the expense of computational time and memory.
The Search Step Size can dramatically affect the time it takes to compute a Plan. A lower value will increase the number of pointings to be tested. A higher value will decrease the number of pointings. The number of pointings in the grid is calculated and displayed next to the selected Search Step Size. Keeping the search grid to less than 10,000 total pointings is advised for MPT plans to run in a reasonable amount of time on most computers.
Search grids that subtend RA = 0.0 cause MPT to fail. This is expected to be fixed in APT 27.0 or later. A workaround may be to break up the source catalog and plan separately.
These parameters are editable by the observer in case they want to limit the search area, or move it to a particular region on the sky. The defined area should typically be within the area covered by the dither pointings.
Note that a fixed single pointing plan may be obtained by setting Width = Height = 0.0 arcsec.
The parameters Width and Height are measured in units of arcsec along the MSA aperture X and Y axes as shown in Figure 2. Typically the values provided by MPT will suffice, but it is sometimes useful to visualize the footprint of the MSA at a specific position using Aladin, the viewer provided by APT, when choosing these search grid parameters. There are additional drawing tools in Aladin that could help determine appropriate values for these search grid parameters.
After invoking Aladin from APT, note that the default view in the APT GUI changes from Form Editor to View in Aladin. In order to return to the MPT, click on the Form Editor at the top left of the main APT window and make sure the correct Observation Folder is selected or highlighted.
MPT Section 7: Other Plan Parameters
Section 7 of the MSA Planning Tool is where the last remaining parameters are defined, the plan is named, and finally generated.
Table 4: Additional Planning Parameters
A user-defined name for a Plan. Use a meaningful name for each plan. An APT file can contain several plans and will save them.
The Plan name will become the name of the Observation if one is created from the Plan and it will NOT be possible to later change the name of the Observation.
If this option is selected, the MSA Planning Tool will reorder the Primary Candidate List based on weight and will select pointings that observe the highest sum of source weights. Typically, weights are present as a column in the input catalog, and are inherited by the Primary Candidate List as explained in the article NIRSpec MPT - Catalogs.
In the absence of weights (or given equal weights), MPT will prioritize targets based on their order in the Primary Candidate List.
If the user chooses to enable Monte Carlo shuffling, the tool will attempt to optimize the number of targets observed in an MSA configuration by shuffling the Primary Candidate List before selecting targets. The number of Monte Carlo trials can be adjusted by the user. The default is 10 trials. The results of all trials are evaluated and the best result is selected. Figure 10 shows the advantages of enabling Monte Carlo shuffling.
There are a few unintended bugs when "Use Weights" and "Monte Carlo shuffling" are used. These are expected to be fixed in APT 27.0 or later.
(1) Use Weights should first sort the sources by descending weight in order to place the most highly weighted sources into the MSA configuration, but the weights of those placed into the MSA at each search grid point will be used to help determine the best result. This option can be used as is, but the fix, when it comes, should improve results.
(2) If weights are present in the Catalog, Enable Monte Carlo will always sort sources by weight after shuffling them (even when Use Weights is turned off), which will undo the shuffling if all sources have unique weights. This option should not be used unless multiple sources in the catalog have the same weight.
|Number of Configuratons|
The number of MSA configurations to generate.
If Number of Configurations is left blank, then MPT will calculate as many MSA configurations as required to completely observe all the Primary Candidates. If this is not desired, make sure to choose a valid number of configurations.
When dithers are specified, the MSA Planning Tool computes the number of MSA configurations needed to observe at all primary dither points to complete the plan for one target set. To observe additional target sets, simply specify a multiple of the minimum number needed to complete one target set.
The tool will guide users by indicating the factor they need to multiply by to obtain more target sets. If a value larger than the minimum is specified, the planning tool will simply attempt to create more target sets from the designated Primary and Filler lists. The new target sets will have the same dither pattern but will have different pointings than the first target set.
For example, if a user elects a 3-point primary dither in their plan, either by adding 2 fixed dithers, or 2 flexible dither constraints, the plan will require 3 MSA configurations for each target set it produces. The user may choose to design 3, 6, or 9, 12, etc. MSA configurations. Each multiple of 3 MSA configurations will produce 1 target set because it takes 3 MSA configurations to complete all the planned dithers for each target set. Primary targets that have been observed in previous MSA configurations associated with another target set derived in the plan will be excluded before attempting to create a new target set.
Generating a Plan
After the plan parameters are fully specified, plan generation is begun by clicking Generate Plan. While the MPT is generating a plan, a dialog window shows the progress. The length of time it takes to generate a plan depends on the number of points searched (shown by the search grid parameters) and the number of science sources in the Primary and Filler Candidate Lists.
If users wish to stop plan generation once started, the stop button can be clicked in the pop-up progress window. This will stop the MPT at a point in between the creation of MSA configurations, and it will populate the MPT: Plans area with the truncated plan. Once the Plan is generated, APT will automatically display the results in the Plans pane (NIRSpec MPT - Plans) where the proposer can examine planning results to assess the quality of the plan.
In order to return to the Catalog or Planner panes, simply go to the top of the window and select from one of the three tabs shown.
Karakla, D. et al. 2014, Proc. SPIE 9149
The NIRSpec MSA Planning Tool for multi-object spectroscopy with JWST