NIRSpec MPT - Manual Planner

The JWST NIRSpec MSA Planning Tool=
(MPT) Manual Planner is designed to help the user manually create new plan=
s and modify existing plans.

Introduction

The MSA Planning Tool (MP=
T) Planner is designed to automatically create optimal plans, but it is also possible for the use=
r to create plans manually. Checking the Manual Planning<=
sup>1 box at the top of the Planner ta=
b of MPT resu=
lts in the view shown in Figure 1.

=20

=20
=20

=20
Figure 1. MPT Manual Planner=20

=20
=20

The Manual Planning template has four sections=
that are described in detail below.

1Bold italics <=
/em>font style is used to indicate parameters, parameter values, and/=
or special requirements that are set in the APT GUI.

=20

=20

MPT Section 1. Planning angles

=
Aperture PA (APA)

A given NIRSpec MSA observation must be executed at a spe=
cific telescope orientation angle so that the selected sources will fall in=
to 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 dur=
ing the year or not available at all. The Target Visibility Tools =
can be used to determine the range of feasible orientation angles for a tar=
get 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-hol=
der or "planning visits" with MPT. Once a proposal is accepted, =
it will be assigned a fixed or=
ientation and a corresponding window of time when observations will be made=
.

For p=
roposal 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<=
/span> the fixed orientation <=
em>APA<=
span style=3D"color: rgb(37,37,37);">that has been assigned to your observa=
tion 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 countercloc=
kwise direction. Figure 2 shows how this angle is measured on t=
he sky. The "Y" axis represents the cross-dispersion direction of the MSA. =

=20
=20

=20
Figure 2. Aperture position angle=20

=
=20
The black arrow represents the North direction. The blue arrows represent t=
he direction of the=20
Ideal X a=
nd Y axes. Dispersion is along the "X" axis. The Aperture Position Angl=
e (=CE=B8) is shown as measured in the sky.
=20
=20

Programs that have an orientation or tim=
ing special requirement added to the observation can restrict scheduling o=
pportunities. Most NIRSpec MOS programs should be submitted without ad=
ded ori=
entation restrictions, in order to allow the schedulers t=
o find suitable windows for them. Also, when the proposal is su=
bmitted, the observer=20
should explicitly add an "ON HOLD for aperture position angle assignment" special requirementto=
their NIRSpec spectroscopy observations.

True angle to target=

The True angle t=
o 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 velo=
city 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 t=
he selected APA is not feasible.

MPT Section 2. Primary Candidate List

The Primary Candidate List is a candidate set that should be defin=
ed in the NIRSpec MPT - Catalogs pane. In manual planning mod=
e, select the appropriate list from the pull down menu.

=
MPT Section 3. Exposure setup

In section 3 of the Manual Planner the observer defines=
the exposure specification. Click the ADD button=
to add a new exposure specification. Each new exposure specification results in one or more new exposures. The =
number of new exposures resulting from an exposure specification is determi=
ned by the dither pattern specified.

The JWST Exposure Time Calculator=
(ETC) should be used to determine the best exposure parameters&n=
bsp;to optimize the signal-to-noise of your observation. An exposure is con=
figured by setting the Grating/Filter combination=
, Readout Pattern, Number of Gro=
ups, and Number of Integrations. &n=
bsp;

The exposure parameters that the observer needs to define are list=
ed in Table 1.

Table 1.Description of Science Parameters for a given exposure

Exposure Parameter

Description

Grating/Filter

Select a grating/filter combinatio=
n from the pull down menu. The article NIRSpec Dispersers and Filters describes all t=
he available combinations for NIRSpec observing modes.

Readout Pattern

Each exposure consists of a set of one or more integrations. Integra=
tions consists of a set of nondestructive reads of the detector.

The detectors can be read i=
n different ways. The available patterns are NRS<=
/em>, NRSRAPID, NRSIRS2=
, and NRSIRS2RAPID. These patterns are described =
in full detail in the article NIRSpec Detector Readout Modes and Patterns. =
span>The default pattern is NRS, whic=
h will average 4 frames on board (i.e. there are 4 frames in one Group). =
span>

Select the pattern that best suits your observation.

Groups/Int

The number of groups in an integration. The number of groups, togethe=
r with the Readout Pattern (i.e. the number of fram=
es 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 exposur=
e, where an integration is defined as a set of non-destructive reads.

Autocal=
span>

This option is available to automa=
tically 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. =
span>

ETC Wkbk.Calc ID

The user should enter the ETC calc=
ulation ID from the associated ETC Workbook. See note below.

Exposure specifications may be reorganized or removed as needed, using t=
he New, Copy and Link, =
and Remove buttons, and the arrows at the left of=
the 'Exposure Setup' box. Each exposure specification will be used for eac=
h of the Pointing and Configurations specified below.

MPT Section 4. Pointing/Config setup

Configurations and Pointings

NIRSpec MSA configurations are described by a =
configuration file. Those configurations can be created with the Manual Planner as described below, or ingested to the =
Manual Planner from the automatic MPT Planner. It is possible to sav=
e a configuration off-line by exporting it from APT. A configu=
ration file may also be imported into APT using the MPT Manual Plan=
ner. The only format supported for importing or export=
ing an MSA configuration file is comma-separated values (.csv).

Click New, Copy and Link<=
/em>, and/or Remove (as shown in Section 4 of Fig=
ure 1) to create or delete the configurations you want. New will create a new MSA configuration entry in the next row of the=
table. Table rows can be rearranged using the up and down arrows to the le=
ft of the table. Copy and Link can be used to mak=
e a copy of an existing configuration (first select the entry you want to c=
opy).

Caution! Any changes made to the configuration (including renam=
ing it) will apply to all table entries using that configuration.

Copy and Link is provided for users who wish t=
o create a set of offset exposures from a Base Pointing, and to save overheads by linking them as a set of dithers applied t=
o the base pointing. The Base Pointing, Dispersion Offset, and Cross-Dispersion Offset=
columns can be edited directly in this table. Offsets are in=
units of shutters.

By clicking on Edit config in the ri=
ght column of a table entry, a window will pop open displaying the MSA shut=
ter view for the selected MSA configuration. This window is the Manual Editor.

As an example, to create a set of nodded exposures that use the same MSA=
configuration in the Manual Planner -

Click New to generate a new MSA configuration=
.

Type in the base pointing.

Type in "0.0" for the dispersion and cross-dispersion offsets.

Click Copy and Link twice to create two new e=
ntries in the table. These will use the same MSA configura=
tion as the first entry.

Edit the second entry cross-dispersion offset to have a value of 1.0 (e=
xactly 1 shutter up from the base pointing).

Edit the third entry cross-dispersion offset to have a value of -1.0 (e=
xactly 1 shutter down from the base pointing).

Click Edit config in the right column of the =
first table entry (at the base pointing). Wait for the Manual Editi=
or window to appear.

Create the configuration you want by opening or closing shutters in the=
Manual Editor.

When finished, click OK.

To save this new Plan, give the plan a unique name, and click Finish Plan at the bottom of the main Planner window.

Manually =
editing a configuration

When the Manual Editor is open, the shutter view is pre=
sented with the sources of the candidate list used to gen=
erate the configuration, as shown in Figure 3. Other lists may=
be displayed by selecting them from the Parameters tab of this window. Note that all =
sources appear as black plus symbols in the Manual Editor,=
whether they are in configured slitlets or not.

=20

=20
=20

=20
Figure 3. Manual editor=20

=20
The configuration of shutters in the four MSA quadrants is shown, using the=
color convention introduced in
NIRSpec MPT - Plans. &nbsp=
;Sources in the
Manual Planner are always colored black.
=20
=20

It is possible to zoom in to view =
individual shutters in the Manual Editor. Zooming in =
or out is accomplished by depressing the right mouse button while drag=
ging up or down. This is usually enabled on a trackpad by depressing two fi=
ngers at once and dragging in an upward or downward motion. Hovering the mo=
use over a single micro-shutter provides its position in the MSA and its st=
ate (commanded open or closed, stuck open or closed, etc.)

Individual operable shutters may be commanded opened or closed with a "L=
eft Click" on the mouse. Also available are the Open all<=
/strong> and Close all buttons. The metadata=
for each open shutter is tracked during load, so opening all shutters in t=
he Manual Editor will be slow and is not recommen=
ded for casual use. The Manual Editor sh=
ould be used to open shutters that correspond to sources of interest, as sh=
own in Figure 4. There is a shortcut to make a long slit configuration: poi=
nt the mouse at a column of shutters, and use "Ctrl+Left Click" to open (or=
close) the column of shutters.

For users who wish to observe movin=
g targets with a long slit configuration at one of the Qu=
adrant 4 Field Points in the MOS Spectroscopy template using WATA, columns =
can be opened in the following locations:

Note that shutters open on sources will be designated as source shutters=
, and others are interpreted as background shutters (for Data Management Sy=
stem (DMS) pipeline calibration). There is currently no mechanism in APT fo=
r a user to specify a shutter without a source as a source shutter for DMS =
purposes (for extended sources, e.g.). Custom MSA configurations planned wi=
thout the use of a Catalog will currently fail to be processed correctly. <=
span class=3D"inline-comment-marker" data-ref=3D"7f47c4c5-b276-425b-a63b-6f=
1500037e62">A fix is expected in APT 27.2.

=20

=20
=20

=20
Figure 4. Manually editing the configuration file=20

=

=20
Detail of the editing process using the=20
Manual Editor. In this example, six shutters have been ope=
ned manually (shown in dark orange) creating slitlets around two sources. N=
ote that the rows corresponding to those shutters will change from white to=
light orange to signify that they should be avoided for adding any other s=
ources.=20
See the note below abou=
t PRISM masking.=20
=20

Options exist to export and import MSA configurations. These optio=
ns, however, are intended for expert users who wish to manipulate MSA confi=
gurations outside of APT. The MSA can only be configured after applying cor=
rections to source positions at the MSA affected by instrument and telescop=
e geometric distortions. A completed MSA configuration can be export=
ed using the Export to CSV button. One can be imp=
orted with the Import CSV button. =
Export to CSV produces an ASCII file of comma-separat=
ed values that can be shared and imported into the Manual Planner=
strong> with Import CSV. The exported CSV file ha=
s values of '0', '1', 's', or 'x'for each c=
ommanded open, commanded closed, failed open, or failed closed shutter, respectively.=
Additionally, an image of the configuration can be saved in SVG format.

APT files themselves can be shared; this is the best way to =
share plans and configuration details. At the bottom of this article is a tip for saving=
the target info from a plan to a table that can be exported and examined o=
utside of APT. This format is more accessible and useful for tracking=
observed target information.

=20

There a a few known problems with the Manual Editor.

Click here for current issues...

The Manual Planner does not differentiate =
between primary or secondary (Filler) targets because that=
concept does not apply here. Sources are currently shown as '=
Contaminants' in the Manual Planner. This should =
be kept in mind when reviewing Plan results in the Plans p=
ane of MPT. This problem does not affect observations, however. It is expec=
ted to be fixed in later versions of APT (in APT 27.2 or later=
).

For PRISM exposures, the masking shown in li=
ght orange in the Manual Editor is incorrect =
in the dispersion direction. Masking is intended to indicate areas to avoid=
when adding new targets to prevent spectral overlaps on the detector. We e=
xpect this will be fixed in APT 27.2 or later. The use=
r is not prohibited, however, from creating slitlets for new targets in the=
masked area. For PRISM exposures, the slitlets should be separated by at l=
east 156 shutters in dispersion to prevent spectral contamination. The equi=
valent distance to factor in for the MSA gap is 86 shutters. This separatio=
n will allow up to 4 sources per row (depending on the source density and s=
patial distribution).

It is easily possible to unintentionally click open a shutter in the Manual Editor. This can cause contamination of target spectra=
if the unintended shutter was opened within the masked region of another i=
ntended target. A warning will be added in later versions of APT (APT 27.2 or later) when this happens, but for now the user is ad=
vised to review the MSA configuration before finishing the Plan to avoid co=
ntaminating the spectra of an intended target.

=20

Continuing with the Manual=
Editor window features - three tabs are located at the bottom of =
the window: Pointing, Parameters, and Collapsed.

Under the Pointing tab (Figure 5) it is possible to give a name to the configurati=
on, and specify appropriate pointing equatorial coordinates. Ba=
se PointingRA and Decvalues are required before the MS=
A configuration can be saved. =
If other MSA configurations have already been designed, their P=
ointing and Configuration will be a=
vailable from the pull-down menus Copy Existing Pointing and Copy Existing Configuration. If the <=
em>Base Pointing coordinates are within the Catalog area, the source positions from the Ca=
talog will appear in the shutter view.

=20

=20
=20

=20
Figure 5. Pointing tab=20

=20
Detail of the Manual Editor. The=20
Pointing tab allows the user to view the base pointing and=
offsets specified in the main window of the=20
Manual=20
Planner, or to specify or change the equatorial coordinate=
s (
RA, Dec) and assign a unique name to the MSA conf=
iguration.=20
Offsets can be specified or altered here, and it =
is possible to select an existing pointing or MSA configuration from alread=
y existing ones.
=20
=20

Under the Parameters tab, a Candidate set must be =
selected, even for plans generated with the Manual Planner=
. This implies that a Catalog is required as well=
. To further ensure that the standard calibration pipeline will not fail, t=
here must be targets in planned slits. Figure 6 shows a detail of the Param=
eters tab design.

=20

=20
=20

=20
Figure 6. Parameters tab=20

=20
Detail of the=20
Manual Editor. In the=20
Parameters tab is shown the list of sources selected in th=
e=20
Manual Planner as described in=20
Section 2. It is possibl=
e to click the=20
Master Background button to indicate the users in=
tent to specify multiple scattered shutters that are to be used for backgro=
und measurements for all sources observed in the MSA configuration. Typical=
ly, background measurements are taken from the adjacent shutters in the sam=
e slit as a source.
=20
=20

From the Parameters tab:

The candidate set can be changed by selecting from the Cand=
idates pull-down menu to show the positions of other sources =
near the sources of interest.

The Master Background button, when selected, =
makes it possible to open scattered shutters in the MSA on areas of the sky=
that will be used for background measurement and subtraction from target s=
pectra.

The Add shutters plane to Aladin button will =
display the slitlets of each target in the Aladin viewer. When return=
ing from Aladin to the main APT window, remember to click 'Form Edi=
tor' in APT to see the normal Manual Planner view=
.

The Collapsed tab view (Figure 7=
) shows each target's pos=
ition in its own shutter, all plotted together in a single virtual shutter.=
The Source Centering Constraint is selecta=
ble, and though it has no effect by itself, it can be used to identify whic=
h planned sources fall outside the margin of interest. These shutter =
constraints are described in the NIRSpec MPT - Planner.

=20

=20
=20

=20
Figure 7. Collapsed tab=20

=20
Detail of the=20
Manual Editor. The
Collapsed tab shows the distribution of planned sources i=
n a single virtual shutter (i.e. only those targets in shutters which the u=
ser clicked open in the=20
Manual Editor window).=20
This view is currently not working but we expect it to be fixe=
d in APT 27.2.
=20
=20

Finally, to confirm and accept this new configuration, click the OK button at the bottom of the Manual Editor window. This will return you to the Manual Planner=
view in APT, shown in Figure 1.

Generating a plan

Under Plan Name in the main window of the Manual Planner, assign a name to this manual plan and click Finish Plan. This will process and generate t=
he plan and direct the user to thePlanspane of MPT, whe=
re it is possible to review and assess the quality of the plan.

After the Plan is saved, and an Observation is created from it, there is=
also a mechanism for saving the planned target info from exposures made wi=
th the Manual Planner or those automatically-generated usi=
ng the MPT. The target positions, pointing, and shutter information c=
an be saved to a .csv file. To do so, click on the "File" item from the main menu at the very top of the computer screen. &n=
bsp;From the pull-down menu, select Export =E2=86=92 MSA Targe=
t Info. This mechanism makes it possible to track target cov=
erage through all exposures of an Observation outside of APT. These files a=
re ASCII and readable by Excel, for example.