MSA Target Info File

Planned sources in JWST NIRSpec MSA-based observations can be exported from APT. The exported information includes shutter position in the MSA and positional offsets within the shutter. 

On this page

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

For any MOS program using an input catalog, it is possible to export or download a list of successfully planned sources directly from APT. This can be done by highlighting the MOS observation in the program in the APT tree or Form Editor (several may be highlighted at once). Then, in the APT menu, click FileExportMSA Target Info as shown in APT Export Files. A pop-up will ask for the destination of the exported files. Multiple files are created, one for each exposure generated by the observation, and one or more for the MSATA exposures containing information about the reference stars. For example, for an observation with one visit containing exposures in one grating with 2 primary dithers and a 3-point nod at each dither point, 7 files will be exported; one for the MSATA and one for each science exposure nod position at each dither position.

The exported files are in CSV format. To help identify which file corresponds to which exposure in the observation, the filenames for the science exposures have a format like “PPPP-obsO-cCeEnN-GGGGG-FFFFF” where PPPP is the program number, O the observation number, C the config number, E the exposure number, and N the nod number. GGGGG is the grating, and FFFFF is the filter. The MSATA file (for each MOS visit), has a filename like "PPPP-obsO-N-TA", where PPPP is the program number, O the observation number, N the number of the TA in the observation, and TA indicates that it is from a TA, not a science exposure.

Science exposures source information

The science exposure MSA Target Info files all have similar column names. Column names in the MSA Target Info file are listed and described in Table 1. The file contains positional information in a variety of reference frames, as well as target spectral wavelength cutoffs on the two NIRSpec detectors. For the wavelength cutoffs, a value of -1 indicates the spectrum starts to the right of the particular detector edge. A value of -2 indicates the spectrum ends to the left of the particular detector edge.


Table 1. MSA Target Info file column description

Column NameValuesDescription
ID
MSA Catalog source ID
Source RA (Degrees)
Right ascension of the source in degrees from the catalog
Source Dec (Degrees)
Declination of the source in degrees from the catalog
Source TypePrimary, Filler, or ContaminantIndicates if the source is from the Primary Candidate List, the Filler Candidate List, or is an unplanned Contaminant from the Catalog

Source MSA Disp (meters)


Location of the source in the MSA frame in the dispersion direction, measured in meters

Source MSA Spat (meters)


Location of the source in the MSA frame in the spatial direction, measured in meters
Orient (Degrees)
The aperture position angle of the MSA for the exposure
Fiducial RA (Degrees)
Right ascension of the exposure fiducial pointing in degrees
Fiducial Dec (Degrees)
Declination of the exposure fiducial pointing in degrees
V2 (arcsec)
The V2 position in the V2-V3 plane of the MSA source in arcsec. The MSA occupies a fixed position within the V2-V3 plane.
V3 (arcsec)
The V3 position in the V2-V3 plane of the MSA source in arcsec. The MSA occupies a fixed position within the V2-V3 plane.
Quadrant  1, 2, 3, or 4The MSA quadrant where the source shutter is located. In the MSA Shutter View, Q3 is upper left, Q4 is lower left, Q2 is lower right, and Q1 is upper right 
Row1 to 365The MSA row that the source shutter is located in within the quadrant, corresponding to the Y (spatial) shutter value shown in the MSA Shutter View in MPT.
Column    1 to 171The MSA column that the source shutter is located in within the quadrant, corresponding to the X (dispersion) shutter value shown in the MSA Shutter View in MPT.
Offset(x)Fraction from 0 to 1.0The X position of the source within the shutter. This is the fractional shutter value in the dispersion direction measured from the upper right corner of the shutter. The full shutter width includes the open area of the shutter plus 1/2 bar width on each side of the shutter. In the orientation of the MSA Shutter View in MPT, offsets start at the upper right mid-bar position.
Offset(y)Fraction from 0 to 1.0The Y position of the source within the shutter. This is the fractional shutter value in the spatial direction measured from the upper right corner of the shutter. The full shutter height includes the open area of the shutter plus 1/2 bar width on the top and bottom of the shutter. In the orientation of the MSA Shutter View in MPT, offsets start at the upper right mid-bar position.
NRS1 Min Wave-1, or wavelength cutoff in micronsDetector NRS1 left edge wavelength cutoff. For values other than -1, this value is the shortest wavelength of the target spectrum on detector 1. A value of -1 indicates that the blue end of the spectrum occurs to the right of this detector edge. 
NRS1 Max Wave-1, -2, or wavelength cutoff in micronsDetector NRS1 right edge wavelength cutoff. For values other than -1 or -2, this value is the longest wavelength of the target spectrum on detector 1. A value of -1 indicates that the blue end of the spectrum starts to the right of this detector edge. A value of -2 indicates that the red end of the spectrum occurs to the left of this detector edge. 
NRS2 Min Wave-1, -2, or wavelength cutoff in micronsDetector NRS2 left edge wavelength cutoff. For values other than -1 or -2, this value is the shortest wavelength of the target spectrum on detector 2. A value of -1 indicates that the blue end of the spectrum starts to the right of this detector edge. A value of -2 indicates that the red end of the spectrum occurs to the left of this detector edge. 
NRS2 Max Wave-2, or wavelength cutoff in micronsDetector NRS2 right edge wavelength cutoff. For values other than -2, this value is the longest wavelength of the target spectrum on detector 2. A value of -2 indicates that the red end of the spectrum occurs to the left of this detector edge. 



MSATA exposure reference star information

In preparation for the MOS program update, the observer will need to update the catalog with suitable reference star candidates (see NIRSpec MPT - MOS and MSATA Program Updates). Using the updated catalog, and after the aperture position angle is assigned by STScI, the user will then select a Reference Star Bin for the MSATA in each MOS visit. Once these steps are completed, the MSA Target Info file for the MSATA exposure will look much like that shown in Table 1, minus the Source Type column.

Note that, depending on the stage of development, the MSA Target Info file for the MSATA exposure will have different information:

  • If no reference star bin has been selected at the visit level in APT, the exported file will be empty.
  • If a reference star bin has been selected for the visit, but the aperture position angle has not yet been assigned by STScI, APT will check for reference stars using the planning angle (Planned Aperture PA) so that users can see what reference stars are available at a selected angle. This can be useful in case proposers wish to add a fixed Aperture PA special requirement on the observation during program development.
  • If an Assigned Aperture PA has been assigned to the MOS observation by STScI, and the observer has also updated their catalog, replanned their observation, and selected reference stars for the resulting visits, then the exported information in the MSATA target info file will contain the reference stars for the assigned angle.




Latest updates
  •  
    Reviewed and minor edits made.
Originally published