- JWST Cycle 1 Proposal Opportunities
- JWST Cycle 1 Guaranteed Time Observations Call for Proposals
- • JWST Director's Discretionary Early Release Science Call for Proposals
- • JWST Call for Proposals for Cycle 1
- 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 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
- •Moving Target Roadmap
- •Field of Regard Considerations for Moving Targets
- •Instrument-Specific Considerations for Moving Targets
- •Moving Target Recommended Strategies
- •JWST Moving Target Observing Procedures
- •JWST Moving Target Calibration and Processing
- •JWST Moving Target Ephemerides
- JWST Moving Targets in APT
- •JWST Moving Targets in ETC
- •JWST Moving Target Useful References and Links
- •Overheads for Moving Targets
- •JWST Moving Target Policies
- NIRSpec IFU and Fixed Slit Observations of Near-Earth Asteroids
- JWST Parallel Observations
- JWST Target of Opportunity Observations
- 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
- JWST Exposure Time Calculator Overview
- • JWST ETC New User Guide
- JWST ETC Calculations Page Overview
- •JWST ETC Creating a New Calculation
- •JWST ETC Backgrounds
- •JWST ETC Wavelength of Interest/Slice
- •JWST ETC Batch Expansions
- JWST ETC Strategies
- JWST ETC Target Acquisition
- JWST ETC Outputs Overview
- JWST ETC Workbooks Overview
- JWST ETC Pandeia Engine Tutorial
- • JWST ETC Point Spread Functions
- • JWST ETC Instrument Throughputs
- • JWST ETC Residual Flat Field Errors
- • JWST ETC NIRCam Imaging
- Astronomers Proposal Tool
- • JWST Astronomers Proposal Tool Overview
- APT Workflow
- Additional APT Functionality
- Getting Help with APT
- 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 Imaging, MIRI MRS, and NIRSpec IFU Observations of SN1987A
- •MIRI and NIRCam Coronagraphy of the Beta Pictoris Debris Disk
- •MIRI IFU and NIRSpec Observations of Cas A
- MIRI MRS Spectroscopy of a Late M Star
- MIRI MRS and NIRSpec IFU Observations of Cassiopeia 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 Deep Field Imaging with MIRI Imaging Parallels
- NIRCam Imaging and NIRISS WFSS of Galaxies Within Lensing Clusters
- •NIRCam WFSS Deep Galaxy Observations
- •NIRCam and MIRI Coronagraphy of the Beta Pictoris Debris Disk
- •NIRCam Coronagraphy of HR8799 b
- NIRCam Grism Time-Series Observations of GJ 436b
- NIRCam Time-Series Imaging of HAT-P-18 b
- 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 AMI Observations of Extrasolar Planets Around a Host Star
- NIRISS SOSS Time-Series Observations of HAT-P-1
- NIRISS WFSS with NIRCam Parallel Imaging of Galaxies in Lensing Clusters
- 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 IFU and MIRI MRS Observations of Cassiopeia A
- NIRSpec BOTS Observations of GJ 1214b
- NIRSpec IFU, MIRI Imaging, and MIRI MRS Observations of SN1987A
- NIRSpec IFU and Fixed Slit Observations of Near-Earth Asteroids
- NIRSpec MOS Deep Extragalactic Survey
- •NIRSpec MOS Observations of NGC 346
- •NIRSpec and MIRI IFU Observations of Cas A
- 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 Coronagraphic Visibility Tool (CVT) is a GUI-based target visibility tool for assessing target visibilities and available position angles versus time relative to the MIRI and NIRCam coronagraphic masks. Placement of up to 3 companions relative to the primary target can be entered for judging impacts from obscurations in the coronagraph fields of view.
JWST observations have pointing constraints because the visibility of a target depends on the target's ecliptic latitude and time of observation. In addition, the allowed roll angle range depends on the solar elongation of the target's position at the time of observation. Allowed position angles (PAs) for a target can thus be a complicated function of time within each allowed visibility window. As a result, it can be difficult to:
- understand the possible orientations of a given target on the detector, especially in relation to any instrumental obscurations,
- determine the ideal roll angles and offsets for multi-roll observations, and
- determine the visibility of two or more targets that need to be observed simultaneously.
The JWST Coronagraph Visibility Tool (CVT) was created to address these issues and assist in planning MIRI and NIRCam coronagraphic programs prior to entering targets and observations into APT. The CVT will help you avoid problems in later APT scheduling and/or help diagnose scheduling errors that may crop up in APT. It is one of two tools available for investigating JWST target visibilities.
Note that the CVT is designed to provide quick illustrations of allowable observation orientations for a given target. While it approximates JWST’s pointing restrictions, it does not query the official JWST Proposal Constraint Generator (PCG) or check for guide star availability, as is done in APT. Therefore, CVT results should be treated as useful approximations that may differ from official APT constraints by a small amount (a degree or so).
Downloading and installing the CVT
The CVT is distributed as part of the AstroConda package from STScI. AstroConda is the preferred release channel for JWST Python-related tools. For more information, see the AstroConda installation instructions. Also note that AstroConda runs from the bash shell, not CSH or TCSH.
If you've already installed AstroConda for macOS or Linux, you can install CVT as follows in the AstroConda environment:
If you're running macOS and want a double-clickable app:
- Download the double-clickable app archive (e.g.
jwst_coronagraph_visibility_calculator_macos_v0.1.0.zip) from https://github.com/spacetelescope/jwst_coronagraph_visibility/releases/latest
- Extract the .zip file to get the .app bundle
- Double-click the .app bundle
If you see a message warning you about opening an app from an unidentified developer, right-click (or control-left click) the icon and choose "Open". This is a security feature of macOS.
If you're using Python with pip:
Using the coronagraphic visibility tool: a step by step example
See also: JWST Position Angles, Ranges, and Offsets.
Depending on how it was installed, you can open CVT from its app or from the command line. Double-clicking the app should open it, or on the command line in an AstroConda-active window, enter "
jwst-coronagraph-visibility-gui". After opening the program, a GUI should appear, as shown in Figure 1. (Initial startup may take a few seconds.) From here, everything is done through the GUI.
In the GUI you will see a control panel on the left and a double plot panel on the right. The control panel has SIMBAD Target Resolver fields, input boxes for decimal RA and Declination coordinates, a Companions frame, Instrument/Mask Selector fields, controls for time sampling, and an Update Plot button.
You can type coordinates into the RA and Dec boxes or use the target name resolver to get coordinates. To find a target, type the target name into the SIMBAD Target Resolver box and click Search. If SIMBAD is unable to find a match, the result "No object found for this identifier" will be displayed. If SIMBAD finds a match, the target’s SIMBAD ID, RA, and declination will be displayed. If SIMBAD cannot resolve a target, you may supply the RA and declination yourself (in decimal degrees).
The program also returns the ecliptic coordinates of the entered coordinate. The ecliptic latitude is of particular interest as the range of available position angles for a given target depends on it. Low ecliptic latitude targets may not be observable at certain angles—you will want to know this prior to specifying it for an APT observation.
Running the calculation
Once an RA and Dec are available in the tool, select the instrument and mask (defaults are NIRCam channel A and NRCA2_MASK210R), then click Update Plot to calculate the target’s visibility.
Figure 2 shows an example for the target HR 8799. The left plot shows the target's visibility windows. The red highlights on the solar elongation line indicate the valid windows. The blue tracks show the allowed position angles for the selected instrument and mask over those windows. The right panel shows the selected mask's field of view (red dashed line), where areas shaded in pink represent various obscurations due to hardware. These will change for different masks after the plot is updated.
The visibility plot shows the solar elongation for the target as a black line, with the observable portions (85°–135°) highlighted in red. This target has two valid windows over the year, read from the x-axis. For each red portion, the plot shows the range of allowed position angles in blue, read from the y-axis. ("Aperture PA" denotes the standard position angle, viz., the angle east from North to the instrument y-axis of the selected science instrument and mask.)
Note that although there are two good windows of visibility for this target, the range of allowed position angles for each of them is fairly restricted. Checking below the coordinate boxes in the control panel, you will see that the ecliptic latitude of HR 8799 is only 24.5°, which restricts the range of allowed angles available at any time for JWST.
You can do things like zoom in on any region of the plot, save the figure to a file, and reset to the original plot using Matplotlib's standard plot interactions, controlled by the icon bar at the lower left of the plot region. Hovering over each icon produces pop-up information about its functionality.
To plot the PA of the observatory V3 axis instead of the instrument/mask combination, click on the V3 PA button on the control panel and then Update Plot. The blue points will be replaced by purple points at the V3 PA values allowed for the observable periods.
Adding companions to the primary target
To plan observations of known companions, disks, or other structures, enable one of the Companions boxes by clicking on the check box in the left column. Specify the companion’s PA (in degrees E of N) and separation, Sep, (in arcseconds) from your primary target. A companion can be thought of as a binary star, an exoplanet, the location of a disk’s major or minor axis, or any sort of reference applicable to the astrophysical scene of interest. One can add up to 3 companions. The locations over time of the 1st, 2nd, and 3rd companions will be marked as tracks in the right panel plot with red, blue, and purple, respectively.
Before you update the plot, select or verify the instrument and coronagraphic mask that you’d like to use to observe the target using the drop-down menus. In this example, we select NIRCam and one of the wedge occulters.
Finally, click Update Plot again to refresh the plots. Figure 3 shows an example for HR 8799 in which we have plotted 3 companions to be observed with the NIRCam SWB mask.
You can now click on a blue point in the left visibility plot to select it; the corresponding companion points in time are marked on the right science detector panel in white. The north and east axes are also shown on the science frame as a solid red and yellow line, respectively. The default active field of view size for the selected mask and detector is also displayed on the science frame as a red dashed border. This is useful in scenarios where the astrophysical scene may exceed the aperture size.
You can zoom in on the plot using the plot controls at lower left. Also, when the cursor is within an active plot region, the cursor values appear at the lower right of the overall plot frame when the zoom controls are not active, so values can be seen directly (rather than reading them off the axes). The units on the left panel are degrees on the y-axis and days on the x-axis, referenced to January 1 of a generic year. (The pattern repeats from year to year.)
Use the zoom icon on the toolbar below the plots to enter zoom mode, which will let you enlarge the plot region of interest in either plot panel. Note that an indicator appears at lower right to indicate when the zoom mode is active. (Alternatively, one can select the pan and zoom feature, but the regular zoom is likely more appropriate for these plots.)
Note that each plot is cached, so you can use the forward and back arrow icons to navigate through previous plots. The home icon restores the original plot.
Alternatively, one can select a companion position in the right panel (click on a red, blue, or purple point) and see the corresponding position appear on the left visibility plot. The corresponding companion points are highlighted in white, and the corresponding PA is highlighted in white in the left panel.
Below the science panel, the separation (in arcsec) and angle on the detector (CCW relative to +y axis) are displayed for each white point. Figure 4 shows a particular observation date and roll angle for the HR 8799 system when all three companions are visible without obscuration.
So far, this exercise has determined a time/angle (aperture PA of approximately 215°) when all 3 companions are nominally visible outside the obscuration of the mask. But for many coronagraphic applications, you may want to observe the target with a roll dither. Figure 5 shows what Figure 4 looks like when we zoom in on the visibility window in the left plot panel.
The vertical width of the blue region in the left panel shows the range of allowed angles available at that particular time. The selection of companion positions in the right panel corresponds to a time when the position angle is skewed toward the bottom of the allowed region in the left panel. If a roll dither is desired, you should check the other extreme of allowed angles 9top of the blue region) to see how a roll dither will change the position of the companions relative to the mask obscuration in the right panel.
For this example, you will see that the companion on the blue track in the right panel rotates into the mask and becomes unobservable when the top of the blue range is selected in the left panel. You can use this sort of analysis to decide on how to restrict the size of the allowed roll offset to prevent this obscuration from happening, or investigate visibility in the other observing window to see if there is an alternative configuration that works better.
In Figure 6, we have now zoomed in on the first visibility window in the left plot and highlighted a time when all three companions are visible outside the wedge obscuration. However, two of the companions are very close to the mask, and once again, checking the availability for roll dithering shows problems. At this point, you will need to decide whether the former option is better, whether to include the small roll dither or not, and/or whether it would be more beneficial to make two observations of the field separated in time instead of using a roll dither.
Finally, for systems with other structure around the primary target, such as a disk with some known orientation on the sky, you can define a "companion" (or two diametrically opposed companions if desired) at the relevant position angle to act as a proxy for the disk structure's position angle versus time in the selected instrument and mask.
The rightmost icon in the plot control menu saves a file with the current plot view. The target name and instrument/mask information is encoded in the plot headers. However, the control panel (including any definitions of companions) is not saved. If needed, we suggest the option of performing a screen grab to save the desired display for your reference.
Checking visibility of PSF reference stars
The other important aspect of visibility for coronagraphic observers is the visibility of an appropriate reference star for point spread function (PSF) subtraction. In the vast majority of cases, the standard observation sequence includes an observation of the nominal science target and the PSF reference star in a contiguous, non-interruptible sequence, meaning that both objects need to be observable at the same time. Hence, once any restrictions on the observability of the science target are known, the CVT should be run on the potential PSF reference star or stars to verify that it's visible at the same time. For a PSF reference star, only the left panel (the visibility plot) is needed. (This can also be done using the General Target Visibility Tool (GTVT) since it does not require information about the coronagraphs.) In the vast majority of cases, the standard observation sequence includes an observation of the nominal science target and the PSF reference star in a contiguous, non-interruptible sequence, meaning that both objects need to be observable at the same time.
The example above demonstrates the utility of looking at the details of potential coronagraphic observations prior to entering observations in APT. APT can provide accurate assessments of visibility windows and check such things as guide star availability for a particular time, but it is not optimized to provide assessments of how the NIRCam and/or MIRI masks impact the observability of known companions or disks. By checking such things within the CVT, you will be able to identify appropriate times and/or angles, and have good confidence that observations will be schedulable when their details are entered into the appropriate APT observation template(s). Alternatively, if the CVT shows that a particular target cannot be observed at the desired angle, it may be time to find a different target; at least you will have found this out prior to entering and trying to process a non-schedulable observation in APT.
The CVT, GTVT, and APT have been tested against each other for consistency. However, as stressed in the introduction, the CVT does not generate official pointing restrictions; you should consider the results as approximate and plan accordingly. For example, you should not rely on this tool to ensure that the orientation on the detector is accurate to within a degree of the reported angle or within a day of the beginning or end of the calculated visibility windows. This tool is not to be used for assessing the placement of any companion on a given pixel of the selected detector. It is for quick look and preliminary planning purposes only, but should result in a significant time savings for coronagraphic proposers.
Additional information on JWST’s pointing restrictions, and how those affect target visibility and available position angles are included in this page: JWST Position Angles, Ranges, and Offsets.
This version was updated Aug. 2, 2017, for compatibility with v 0.3.0 of the CVT tool.
This page has no comments.