JWST user documentation is under development; current versions are preliminary and subject to revision.

Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Content Layer
id277319515
Content Column
id277319517
Content Block
overflowauto
nameSummary
id277319516

The Plans pane in the MSA Planning Tool provides the user with a view of observation planning results from the MPT, including statistical information about the generated configurations. It is in this pane where plans can be merged and observations are finally created.

Content Block
overflowauto
nameContent
id277805920

Introduction 

Once a plan is created using the Planner in the MSA Planning Tool (MPT), the user can review the results with the help of the information in the Plans tab. This tab contains information to help assess the merit of the created configurations and it also provides  some statistics that users might find useful before creating a final observation.

The MPT Plans tab has the structure shown in Figure 1, where 5 sections are highlighted. These are described in detail below.

 

Figure container
Figure title

Figure 1. The plans tab

 



Anchor
section1
section1
Anchor
Plan
Plan
Anchor
Description
Description
MPT Section 1:  Plan & Description  

This section contains a pull-down selection of the generated plans for your APT session, and a description box listing the parameters used in the particular Plan selected from the pull-down menu.  Since several plans can be generated in the same APT file, the user should first select a Plan by name. 

 


Anchor
section2
section2
Anchor
Pointings
Pointings
MPT Section 2: Pointings

The MPT generates configurations based on the parameter Number of Configurations defined in the Planner pane. For the example shown in Figure 1, four exposures were generated, each with a slightly different pointing and different MSA configuration. These four exposures are listed in the Pointings table with names that concatenate the MSA configuration id and exposure id. For example, in this case we have four configurations c0, c1, c2, c3 each with one exposures e0, so the names are c0e0, c1e0, c2e0 and c3e0. For each exposure listed here, the right ascension, declination, and aperture position angle (shown as "Orient"), are given (see Figure 2).

NIRSpec MPT: Plans,  Video 1:  Plan Description and Pointings 


Figure container
Figure title

Figure 2. Pointings section of the Plans tab

Figure caption

The generated pointings are listed in this table. The naming convention is described in the text. The "Show" buttons produce the Shutter View (Figure 3) in a pop-up window. The "Send Targets to Aladin" buttons create an Aladin plane with targets positions that are automatically displayed in Aladin.

The Target set size indicated on each exposure line gives the number of targets in the exposure, and the total weight indicates the sum of all target weights in the exposure. (The weight of each target is assumed to be 1 if target weights are not used during planning). A fraction of the targets in each exposure may not be found in other exposures, therefore the total weight may be different for different exposures in the list.  Each exposure can be visualized in Aladin using the "Show" button.

Figure 3 shows the MSA Shutter View of configuration c0e0. This is a pop-up window that appears after clicking the "Show" button. It may take a few seconds to generate. In the MSA Shutter View, the four MSA quadrants are shown. From left to right and top to bottom, the quadrants ID is : 3, 1, 4, 2.

Over-plotted are the Primary sources (green),  the Filler sources (blue), and the Contaminants (black).  A source is classified as a contaminant if it is a source in the catalog, falling in an open shutter, where it is not the source that the shutter was intended to open on.

Tables 1 and 2 explain the color codes for shutters and sources respectively.

Tip

Clicking on a catalog in the list will display that catalog (if it is not already there). In order to remove the catalog from the display simply command-click on the catalog that you want to remove.

Zooming to shutter level, as shown in Figure 4, it is possible to visualize individual sources and slitlets. 

Tip
Zooming to shutter level is accomplished by clicking the right mouse button and dragging up and down. This is usually enabled on a trackpad by depressing two fingers at once and dragging in an upward or downward motion.

Note that hovering with the mouse over a shutter will display the shutter location in the MSA (quadrant, shutter ID in dispersion, shutter ID in cross-dispersion).  Hovering the mouse over a target symbol will display the Source ID from the input Catalog. Figure 3 shows that in the example, the mouse is on Source 198.

At the bottom of this window, there is the "Add shutters plane to Aladin" button. This button automatically creates an Aladin plane containing the slitlets used for this exposure and displays them, allowing users to see the targets in a given exposure together with their MSA slitlets. 

Figure container
Figure title

Figure 3. MSA Shutter View

Figure caption

Sketch of the source positions in the MSA plane.  Note that stuck closed shutters and shorted rows and columns are shown in grey, and sources appear in blue, green and black symbols.  Orange shutters are areas which have been masked out to prevent spectral contamination.

The "Export to CSV" button in the MSA Shutter View saves the configuration file as an ASCII file of comma-separated values.  The file contains a value of '1' for commanded open shutters.  Failed open shutters have a value of '0'  and those with a value of 'x' in the CSV file are failed closed shutters or otherwise inoperable shutters.  The failed shutter positions are inherited from the current MSA operability reference data that the MPT utilizes during plan creation.

The "Save as svg" button in the MSA shutter View  saves this view as an SVG image which can be displayed using a browser.

 

Figure container
Figure title

Figure 4. Zoomed Section of the MSA Shutter View

Figure caption

Zooming to the micro-shutter level, each individual shutter can be seen. Sources are plotted with colors that distinguish between whether they are Primaries, Fillers, or Contaminants, and with symbols that indicate whether they are observed in this exposure, or elsewhere in the Plan. See Tables 1 and 2 for a description of the colors and symbols.

Table 1. Shutters color and meaning

Shutter colorDescription/ meaning
light orange

This color indicates shutters that were masked during the creation of the MSA configuration.  

Adding a new source slitlet anywhere in this area will cause spectral contamination on the detector of the added source's spectrum and spectra of other existing targets in the MSA configuration.  

The number of shutters in light orange indicates how complete is the utilization of the MSA.

orangeThe shutter is commanded open and part of the slitlet
light redThe area marked in this color is impacted by the presence of a failed opens shutter (several rows may be impacted completely or partially.)
redShutter is failed open.
grayShutter is either failed closed, vignetted, or is in a shorted row or column.  These types of shutters are avoided during planning. Cannot be used in any observation.
white

This area is available. MPT did not find sources to fill this space.

Only the white areas of the MSA configuration would be available to add extra background shutters, for example, with the Manual Planner.

 

Table 2. Symbol color and meaning

SymbolDescription/ meaning
green dotSource from the Primary Candidate List that is a successful MSA target in the displayed exposure.
green plus symbolSource from the Primary Candidate List that is a successful MSA target in another exposure of the plan.
blue dotSource from the Filler Candidate List that is a successful MSA target in the displayed exposure
blue plus symbolSource from the Filler Candidate List that is a successful MSA target in another exposure of the plan.
black dotContaminant source present on this exposure.
black plus symbolContaminant source present in another exposure of the plan.

There is a second exposure view present in the pop-up window called the "Collapsed Shutter View" which can be accessed by clicking "Collapsed Shutters" icon as shown in Figures 3 and 5. This view (Figure 5) shows each target's position in its own shutter, all plotted together in a single virtual shutter. Clicking on a symbol will indicate the source ID and will highlight it in the color magenta. It will also highlight the same source if it is present in a second pop-up exposure view of this or another exposure in the plan.

Figure container
Figure title

Figure 5. Collapsed Shutter View

Figure caption

Sketch showing the position of the sources in exposure c0e0 of the example above within a single micro shutter. See Tables 1 and 2 for a description of the colors.

Anchor
aladin
aladin
Aladin Viewer

Aladin is APT's image viewer.

 

NIRSpec MPT: Plans,  Video 2:  Aladin Viewer 

The "Add shutters plane to Aladin" button located at the bottom of the MSA shutter view will draw a sketch of the shutters that comprise the target slitlets on the Aladin sky view, as shown in Figure 6. The shutters in this case are drawn in green while the sources from two candidate sets are in red and blue.

Figure container
Figure title

Figure 6. Displaying slitlets using Aladin


All Aladin features are available to the observer. One useful feature consists of overlaying  the sources and slitlets on top of an actual image of the region of interest. In order to load an image from your computer, simply click on the 'Server selector' form: this is the yellow 'file' icon on the top left corner of the GUI as shown in Figure 6. This will open a new window shown in Figure 7. Select the tab  'File' on the top of this window. From here you may browse to the location of the FITS file in your computer and select it. To display it in the Aladin viewer, click on the SUBMIT button at the bottom of the window.
Figure container
Figure title

Figure 7. Aladin server selector

Figure caption

The 'File' tab is highlighted here to select a FITS file from your computer. There are several image server options available from the menu on the left side of the window. Catalog servers are listed on the menu in the right side of the window.

 


Aladin visualizes the ingested data in a stack of 'planes' located to the right of the window. Each plane represents a catalog or image. It is always possible to re-order the planes. The user's eye is on the top of this stack and sees all activated planes by transparency.  Figure 8 (left) shows an example of the Aladin viewer where a candidate set is displayed and the three-shutter slitlets are over plotted. In Figure 8 (right) we display the HST image that was used to create the parent catalog as background. The same sources are displayed and the slitlets are also shown for comparison.

 

Figure container
Figure title

Figure 8. Displaying slitlets using Aladin


 
Figure caption

Aladin allows the user to display 'planes' that contain useful information such as background image(s), catalog(s), and MSA slitlets. These can be turned on or off.


Anchor
section3
section3
Anchor
TargetSetOperation
TargetSetOperation
Anchor
Targets
Targets
Anchor
Coverage
Coverage
MPT Section 3: Targets and Coverage

In Section 3 it is possible to visualize basic statistics about the plans and target sets.  A target set is the subset of sources from the input Catalog that are observed over a complete set of dithers specified in the plan.  During plan generation, one or more target sets may be created depending on the number of MSA configurations the user specified.  For example, if a set of dithers requires 3 MSA configurations to complete a target set, then the final plan would contain two target sets if the user specified 6 MSA configurations in the 'Number of Configurations' area in the MPT: Planner tab. 

Target results can be filtered in different ways for users to be able to assess their plans. First, click to highlight exposures you are interested in within the Pointings area (e.g. all exposures for the first target set, or, one set of dithers). Note that the exposures are listed in the sequence for each nod set, grating and MSA configurations and dithers.  The NIRSpec MOS observation sequences are set up to minimize the reconfiguration of the MSA, with nod position changing most frequently from row to row in the table, then grating, then MSA configurations and dithers.

When you first land in the Plans pane and by default,  you will have all exposures selected at once. Next, select the "Target Set Operation"  that you would like to perform on the selected exposures, along with a Target type (see Figure 9).  For example, suppose you have a plan constructed with a single primary dither, and a set of 3-shutter nods at each primary pointing.  It would have 2 MSA configurations, each with 3 exposures.  If you are interested in seeing all of the Primary targets that are successfully observed through the dithers, highlight all the exposures, choose Target Set Operation = "Targets in all selected exposures", and select Target type = "Primary targets".

The results of filtering will be shown in the space below the filters.  The number of targets will be summed and displayed, followed by a table with an "x" indicating which targets are in each exposure. You may click on the column name to sort the table by this column. Drag and drop columns to reorder them.  

Tip

MPT has an added feature that could be useful for visualizing the location of sources on the MSA or within slitlets: If the 'MSA Shutter View' or 'Collapsed Shutter View' are open, clicking a source in the target table will highlight it in magenta.

At the same time, a histogram depicting number of targets as a function of number of exposures (the coverage) is also plotted at the bottom of the Pans Tab. This plot is useful to rapidly assess the completeness of the configuration. The "Send to Aladin" button shows the targets using the Aladin interface as described in Section 2.

Figure container
Figure title

Figure 9. Target Set Operations


Anchor
section4
section4
Anchor
Timing
Timing
MPT Section 4: Timing

Section 4 is primarily for testing purposes. It lists the number of configurations that were generated, the number of targets  that are observed, durations, and it also provides a score.

The iteration duration is the time it took to create the first target set, and the Planning Duration gives the total time it took to make the Plan.

The score is a number used by MPT to quantify and select the most successful plan. The higher the score the better.



Anchor
section5
section5
MPT Section 5: Plan operations and creation

Section 5 contains four buttons. 

  • Delete Plan
  • Manual Editing
  • Merge Plans
  • Create Observation

Delete Plan

This button allows the user to discard the selected plan.  In cases where many test plans have beed created, deleting unused plans can improve APT performance. In particular, opening a saved APT file can require a very long duration when it contains many MPT plans.

Manual Editing

It is possible for the user to edit plans manually. Clicking the Manual Editing button opens the selected plan in the manual planning view of the planner tab. For information about the fields shown in this view and how to edit a plan, see NIRSpec MPT: Manual Planner.

Merge Plans

By definition, an observation is created from a single plan.  The merging plans button was added to allow observers to put one or more independently developed plans into a single plan, in order to create one observation.  This is especially useful for potentially minimizing overheads for guide star and target acquisitions when all plan pointings are in close proximity (within the visit splitting distance).

Before creating an observation, users will create several plans and assess their quality and completeness.  It is then possible to merge the best plans into one single plan.  This might be done, for example, if prism and grating MOS observing plans were generated separately to ensure high multiplexing with no spectral overlap in any exposures.  By clicking on the "Merge Plans" button, the user is prompted to select which plans to merge as shown in Figure 10. Simply select the plans that you want to merge, and assign a name to the resulting plan.

Figure container
Figure title

Figure 10. Merging plans dialog window

Figure caption

Merge plans window that allows the user to select plans to be merged from a list of existing plans.

Once the plans are merged, a new merged plan is created and displayed. Note that the naming convention for the individual pointings now contains the plan number as well. In the example shown in Figure 11: p1c0e0, p1c1e0, etc.


Figure container
Figure title

Figure 11. Merged plan

 

Figure caption

Note the nomenclature of the merged plan pointings at the top of this Figure.

Anchor
observation
observation
Create Observation

The purpose of the "Create Observation" button is to gather all the information from the current plan, and send it to the MOS observation template to populate pointings, MSA configurations, instrument and exposure parameters.  Doing this will also construct Visits within the Observation.  The visit structure will depend on the list and order of pointings in your observation, and the Visit splitting distance for the observation pointing.  You may learn more about this in the article JWST APT Visit Planner.

 


 

Content Block
overflowauto
nameRelated links
id280628021

Related links

NIRSpec MOS APT Guide
NIRSpec MOS Proposal Checklist
NIRSpec MPT: Catalogs
NIRSpec MPT: Planner
JWST APT Visit Planner
JWST APT Aladin Viewer
JWST APT Smart Accounting 
Aladin Sky Atlas
Aladin Sky Atlas Manual

Content Block
overflowauto
nameReferences
id281944791

References

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

Content Column
id277319512
Content Block
overflowauto
nameIcon
id278719485

Multiexcerpt include
MultiExcerptNameAPT icon and name
PageWithExcerptMR:APT icon and name

Content Block
overflowauto
nameUpdates
id1066359141
HTML Wrap
padding0
margin0
idupdatesbox
HTML Wrap
tagspan
classupdatesbox-heading

Last updated

Updated July 6, 2017

  • Added Video 1: Plan description and pointings

  •  Added video 2: Aladin viewer

  • Added video: Using the Aladin viewer in MPT


Published June 2, 2017


 

Comment

The format for 'Last updated' is shown below. Enter updates above this internal"Comment" box. Only enter major updates (not typos or formatting changes).


Updated April 5, 2017

  • Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam fermentum vestibulum est. Cras rhoncus. 
  • Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Sed quis tortor. 

Published March 2, 2017


Restrict Content
groupsconfluence-authors

Tables are only visible to JDox content providers

"Updated" refers to the updated or publish dates for the public pages.

Page properties
idcomments
UpdatedJuly 6, 2017
Open commentsNo
TeamAPT NIRSpec
AuthorBeck, Ubeda, Wisklowski
Page properties
idlayout
UpdatedJuly 6, 2017
Fix pageNo
Type-
Teameditors