APT Mosaic Planning

Many JWST instrument modes permit users to specify mosaics to increase the overall field of view of their proposed observations. Mosaic properties can be set in the Astronomers Proposal Tool (APT) and viewed on Aladin.

On this page

See also:  JWST Mosaic Overview and the APT Simple Mosaic Example

 Specifying Mosaics in APT Video Tutorial

The mosaic functionality in APT allows you to define patterns of an instrument's field of view (FOV) that cover regions of the sky that are larger than that available for a single pointing. Each element of the mosaic is referred to as a tile. Mosaicking can be appropriate for both imaging and spectroscopic modes, and also for multi-visit or intra-visit applications, depending on the FOV that is being mosaicked. Table 1 shows the instrument templates for which the mosaic functionality is allowed by APT.

 Table 1. APT science templates allowing mosaics

Table notes:

  • MIRI MRS is a special case since the field of view sizes for the 4 MRS wavelength ranges are different from each other.

  • Time-series modes, coronagraphy, NIRSpec multi-object spectroscopy, and templates for observations of individual targets are not useful for mosaics; to avoid confusion, mosaics have been disallowed in those templates.

The Mosaic Parameters page in the Proposal Parameters documentation section has more details and example figures. Also, see a video help example:  Specifying Mosaics in APT.

The screenshots below are from the APT Simple Mosaic Example demo proposal. 

Due to ongoing development of APT, minor differences in the GUI appearance compared with the screen shots below may occur, but the functionality being shown is still accurate. 

Planning mosaic observations in APT

Basic functionality 

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

An instrument configuration that's compatible with mosaics is first specified in the APT observation form's Instrument and Template fields. To enter mosaic properties, click on the Mosaic Properties tab to show parameters such as the number of tiles in rows and columns, and the amount of overlap to assume. APT and Aladin will position the mosaic tiles using information about the defined instrument aperture or FOV that's stored in the Science Instrument Aperture File (SIAF). As of APT 25.1, the instrument displays are accurate, including detector gaps and offset angles as appropriate.

An initial selection of rows and columns creates a tile pattern that is symmetrical (rectangular or roughly square, depending on FOV shape and row/column selection). APT also provides a row/column shift option that can be used to skew the tile pattern for certain asymmetrical cases. (See the Mosaic Parameters page for details.) You can visualize the resulting mosaic in the Aladin Viewer (Figure 2). By iterating between various assumptions for number of rows and columns, and using the Aladin display, you can adjust those assumptions as necessary for a given science program or sky area to be covered. The following figures demonstrate a few basics in APT and Aladin.

Figure 1. APT control panel for mosaics showing a simple 4 × 2 NIRCam imaging mosaic

The APT control panel for mosaics is shown for a simple 4 × 2 NIRCam imaging mosaic. A 10% tile overlap is the default but you can change this value as desired. (5% is used in the example.) Although this figure is for NIRCam, the mosaic interface for the other instruments is exactly the same. In the Visit Splitting field, above Mosaic Properties, the Splitting Distance is calculated by APT for each target. Its value is reported, for your information, in the gray field box but cannot be edited. In some cases the tile overlap can be increased to obtain more than one mosaic tile in a single visit, thus reducing overheads from guide star changes.
Figure 2. The default Aladin display based on Figure 1 projected onto DSS imaging data

The resulting Aladin display from the Figure 1 example, projected onto DSS imaging data for M83. Note: the NIRCam field of view shown here was displayed using a new feature as of APT 25.1: the "Single Aperture" option in the APT Aladin control window. This hides the dithers and field of view details (likes detector gaps) and simplifies the visualization of source coverage. In practice, as in this NIRCam example, dithers and mosaics should be used in combination to observe a large area without gaps in sky coverage.

Mosaic rotations and skews

See also: JWST APT Help Features page  or these tutorial videos: Aladin Overview in APT, Using Aladin and APT Visit Planner, and Specifying Mosaics in APT.

To understand mosaic planning, it is important to know how APT defines a mosaic. A single target coordinate at the center of the tile pattern defines the mosaic pointing. APT (and Aladin) then calculates the offset positions of each tile relative to that reference coordinate based on the selected instrument/FOV, the specified overlap, and the assumed position angle (PA). Here, "position angle" refers to the angle (degrees eastward from north) of the particular instrument's reference axis (this is also referred to as "aperture position angle" or APA elsewhere). See JWST Position Angles, Ranges, and Offsets.

As the assumed position angle of the mosaic on the sky changes, the entire pattern rotates about the mosaic coordinates. If the region to be observed is circular or at least nearly symmetrical, the rotation of the tile pattern on the sky is of little consequence and scheduling flexibility is maintained, based on other considerations or limitations of the observatory pointing constraints. If the region of interest is significantly asymmetric, it may be necessary to restrict the position angle range of the mosaic (perhaps modulo 180° if visibility allows) in order to maintain efficient coverage of the region of interest. This should only be done in cases where the science drives the constraint, as too many constrained mosaic observations may cause scheduling issues for the observatory. Also, constraining the position angle of a mosaic is a constraint in time as well. Since the IR background at a given position on the sky is also time dependent, imposing orientation constraints may conflict with the desire for low zodiacal background—see JWST ETC Backgrounds for more information.

The Aladin Viewer is an important and useful tool, but some aspects of its functionality for JWST are still not fully developed. The Aladin display will show a default orientation (north up for the reference axis of a given instrument FOV). However, the actual position angle will depend on the ultimate scheduling of the observation, including whether special requirements are added to restrict the observation.

The Aladin display can show the positioning of the mosaic overlayed on the Digitized Sky Survey (DSS) or other images, and can also overlay the positions of catalogued sources. Changes in the positioning of the mosaic are reported back to APT and can be commmited into the target specification in APT (if desired) with a simple click. However, neither APT nor Aladin checks the visibility constraints automatically. You need to run the Visit Planner separately to investigate whether your chosen position angles can be scheduled. Checking the modulo 180° option requires specifying the alternate PA range and running the Visit Planner again. Once the Visit Planner has been run, the Aladin display will then provide visual aids to show the allowed PA range(s) by selecting the observation of interest in the APT form editor, clicking View in Aladin, then in the Aladin interface, click the Orient ranges icon.  

Figure 3. Mosaic from Figure 2 shown with a row shift set to 20

A row shift of 20 applied to the mosaic from Figure 2, which offsets the rows as shown. Note that "20" actually refers to the angle between the same tile corner on 2 adjacent rows. Column shifts can also be applied, either separately or in conjunction with row shifts. Figure 1 shows the controls for adjusting these parameters.

The numbers used in the mosaic row shift and column shift are actually angular units in degrees. (Figure 3 shows how the row shift of 20 is applied as the 20° reference angle.) Because this can be non-intuitive, it is always a good idea to use the Aladin display when adjusting and selecting values for these parameters.

Figure 4. Result of manually rotating the mosaic from Figure 3

The result of manually rotating the mosaic from Figure 3. Note that the reference position has remained constant but the entire mosaic tile set is rotated. If this represented a real angle of interest, the schedulability at this angle would need to be verified separately by running the Visit Planner on the observation.

Note that some JWST instruments have gaps between detectors or detector segments that may affect the uniformity of spatial coverage in the resulting mosaic. Some smaller gaps can be covered by dithering, but uniformity may still be an issue. The situation can be judged by careful inspection of the Aladin display, using the full details (Not the "Single Aperture" display option that simplifies the display). Consult the individual instrument specifications for NIRCam, and MIRI in particular, to understand the geometry of their fields of view. 

Small FOV mini mosaics

Most of the information above applies to imaging mosaics, but smaller FOV mosaics are also possible, and have some differences from standard imaging mosaics. For example, a mosaic with the NIRSpec IFU (which only has a 3” FOV) or the MIRI MRS (several overlapping small FOVs) will likely all be within one guide star region and can be scheduled within the same visit. Because of this, the ordering of activities in a mini mosaic is handled differently from regular mosaics, both for reasons of efficiency and to save mechanism motions. (This is not obvious to APT users but you should be aware it is happening behind the scenes.) There are 4 APT observation templates that are in the category of mini mosaics, where the revised ordering of activities is applied. These include: NIRSpec IFU, NIRSpec fixed slit, MIRI MRS, and MIRI LRS modes. Note, however, that this activity ordering does not apply to other templates, such as NIRCam mosaics with subarrays, until further development in APT is undertaken to support it.

Another functionality that may find utility more so in mini mosaics (although it is technically available for larger mosaics as well) is the idea of a sparse mosaic, or a mosaic with a negative overlap of the tiles (e.g., gaps between the tiles that are not observed). An example might be a small planetary nebula or a Herbig-Haro object that is extended by ~20"–40". Performing a full IFU mosaic over such an object would likely be prohibitive (if not overkill from a science perspective). A sparse mosaic might be used to sample across such a structure at a regular separation but without full spatial coverage. In this case, the sparse mosaic model does apply to NIRCam subarrays, which can be used to mosaic bright objects such as Solar System targets (e.g., planets).

Schedulability checking and problem resolution

See also video help:    APT Visit Planner

Once a desired mosaic observation has been fully specified in APT (including position angle constraints, if needed), the observation should be run through the Visit Planner, which checks the schedulability of the request.

For larger FOVs like the imagers, it is likely that many mosaic tiles will each have their own visit. The Visit Planner not only looks at the available target visibility windows but also steps through the allowed position angles looking at other factors such as guide star availability for each tile as a function of time/position angle. 

For mosaics with just a handful of tiles, it is almost always the case that all the tiles have available guide stars so that the entire mosaic can be scheduled in the same visibility window. However, it must be expected that there will be situations that are more pathological, e.g., no visibility period when all tiles have guide stars simultaneously. This might be more likely for highly constrained asymmetrical mosaics or larger mosaics (under the assumption that the more tiles you have, the more likely that one or more tiles may not have a guide star available at a given time).

The APT Visit Planner provides feedback in cases such as this to help diagnose which constraints are preventing the observations from scheduling. For instance, a right-click on an observation in the Visit Planner window brings up a menu of options, as shown in Figure 5.

Figure 5. Menu of available options displayed by right-clicking in the APT Visit Planner

Menu of available options displayed by right-clicking in the APT visit planner

A screen grab from APT shows the menu of options available with a right-click in the Visit Planner that provide feedback on the schedulability of selected observations.
You can experiment with these options to see the available feedback. One useful tool for mosaic planning is to select the Guide Star Availability by V3PA for Observation option, which produces the graph in Figure 6.
Figure 6. Diagnostic graph showing number of visits with available guide stars as a function of V3 axis position angle

Diagnostic graph showing number of visits with available guide stars as a function of V3 axis position angle

This diagnostic graph shows the number of visits (tiles in this case since each tile is a visit) that have guide stars available, as a function of V3 axis position angle, but this is effectively versus time. In this case, there are 2 periods where all 8 tiles are judged to have guide stars, If there were no periods when all 8 tiles had guide stars at the same angle/time, then the visit planner would have said the observation was unschedulable and corrective action to remove the problem tile (or tiles) would be needed.

In the exceptional case where all of the tiles cannot be observed simultaneously but full spatial coverage is required, there are mitigation techniques that can be applied, as explained below.  

Tile splitting and removal process

See also: APT Mosaic Tile Splitting Activity

What should you do if there is no time when all tiles can be scheduled simultaneously? Diagnostic plots and other information in APT can be used to find the problem visits/tiles. Depending on the specifics, one or more tiles can be removed from the mosaic (if the remaining coverage is acceptable to your science case), or the problem tiles can to be removed from the primary mosaic and scheduled at a different angle/time from the remainder of the mosaic.

For example, let's say there is a window where all but one of the tiles are schedulable. Your may split the problem tile out of the mosaic and create a separate observation for the problem tile, which can then be observed at another time (and angle) when it has guide stars. If one or more tiles need to be split from the mosaic, this splitting must be done in such a way that the split tiles remain associated with the main mosaic for data processing purposes. Since the split tiles will only be schedulable at a different aperture PA (APA) from the main mosaic, this may leave gaps in the coverage. If this is unacceptable to the science case, then a new tile or tiles can be added to the split observations to cover the missing region.

The tile splitting functionality is complicated enough that it is described in a separate article. 

Strategies for planning large mosaics

Although it is not a hard and fast rule, in general, the larger the mosaic the more unlikely it will be that all tiles can obtain guide stars simultaneously. Since removal of individual tiles is cumbersome, you may wish to try other strategies for covering a region of interest.

One such strategy is to define a number of smaller mosaics that cover the region of interest. Letting each smaller mosaic schedule without constraining the PA may make them schedulable, but may also create holes in the desired spatial coverage. This can be partially addressed by increasing the amount of overlap between the smaller mosaics or adding more tiles (the latter being at the expense of additional resource usage). It is left to you to experiment with these techniques and decide how best to proceed for your particular situation.

Another potential caveat may arise for large mosaics (such as a large number of tiles and/or multiple filter imaging mosaics). If an observation specification contains too many visits, linking the visits properly in APT can take a long time to process in the Visit Planner runs (if indeed it does not crash APT altogether). Currently, up to ~200 linked visits can be processed in reasonable time, and performance degrades quickly above this value. The number of visits in your observation can be judged from within the Visit Planner, before attempting to process it.) For practical reasons, then, it makes sense to limit the size of mosaics. The goal of scheduling larger mosaics can likely be accomplished by scheduling 2 or more smaller mosaics covering the desired region.

Uniformity of coverage in mosaics

See also: examples in the articles on NIRCam Primary Dithers and MIRI Imaging Dithering.

Uniformity of coverage for mosaics is dependent on several things: any gaps in the pattern of detectors used for a given instrument, the dither pattern specified for a given observation, and on the mosaic parameters chosen (like degree of tile overlap).   

As also mentioned in the article on dithering, the choice of dither pattern affects the overall size of a given mosaic tile footprint, and thus also impacts the assessment of the uniformity of coverage within a given mosaic. Tile overlap in the mosaic definition can also improve coverage of "edge effects" from the dithering of each tile and improve the uniformity of coverage.

Latest updates
    Updated Figure 1 and video help links.

    Removed NIRSpec MOS from allowed mosaics, per NIRSpec team instruction.

  • Text and links updated

  • Figure 2 and caption updated, 
    Figures 3 and 4 updated
Originally published