Ctrl+K

Data Analysis Plugins#

The Imviz data analysis plugins are meant to aid quick-look analysis of 2D image data. All plugins are accessed via the plugin icon in the upper right corner of the Imviz application.

Imviz Plugins

Metadata Viewer#

This plugin allows viewing of any metadata associated with the selected data.

If the data is loaded from multi-extension FITS that contains a primary header, you will also see a Show primary header toggle, when enabled, would display just the primary header metadata.

Plot Options#

This plugin gives access to per-viewer and per-layer plotting options.

See also

Display Settings

Documentation on various display settings in the Jdaviz viewers.

Subset Tools#

This plugin allows you to select an existing subset to modify, or to select Create new to create a new subset by selecting and using the region selector in the spectrum viewer toolbar. You can also choose the operation that will be applied by the selector tool. Note that these are synched with the subset tools in the app-level toolbar. It might not show some static regions loaded via the API unless an interactive region is drawn after.

If an existing subset is selected, the parameters of the subset will also be shown. Note that in addition to parameters for compound regions (e.g., a subset with multiple disjoint regions) being displayed, the logical operations joining them (OR, AND, etc.) are shown as well for each region. This shows how all regions are added together to create the subset shown in the viewer.

For a simple subset or group of subsets in Imviz only, you can choose to recenter based on the selected Data. To switch to multiselect mode, click the icon in the top right of the plugin and select multiple subsets from the drop-down menu. The centroid is calculated by photutils.aperture.ApertureStats.centroid, which is the center-of-mass of the data within the aperture. No background subtraction is performed. Click Recenter to change its parameters and move it to the calculated centroid. This may take multiple iterations to converge.

Note

If you want accurate centroid calculations, it is recommended that you use a background-subtracted image. Alternately, you could calculate the centroid outside of Jdaviz (e.g., using photutils) and then manually edit the subset (see below) or load your own aperture object (Importing regions via the API).

For a simple subset, you can edit its parameters by changing the values in the corresponding editable text fields. Once you have entered the new value(s), click Update to apply. You should see the subset parameters, shape, and orientation (if applicable) all update concurrently.

Angle is counter-clockwise rotation around the center in degrees.

Markers#

This plugin allows for interactively creating markers in any viewer and logging information about the location of that marker along with the applicable data and viewer labels into a table.

With the plugin open in the tray, mouse over any viewer and press the “m” key to log the information displayed in the app toolbar into the table. The markers remain at that fixed pixel-position in the viewer they were created (regardless of changes to the underlying data or linking) and are only visible when the plugin is opened.

In Imviz, the table also exposed columns labeled “pixel:unreliable”, “world:unreliable”, and “value:unreliable”. These will be logged as True in cases where the information is outside the bounds of the reference image’s WCS (noted in the mouseover display by the information showing as grayed).

From the API#

To export the table into the notebook via the API:

markersplugin = imviz.plugins['Markers']
markersplugin.export_table()

Orientation#

Note

This plugin was previous called “Links Control”.

This plugin is used to align image layers by pixels or sky (WCS). All images are automatically linked by pixels on load but you can use it to re-link by pixels or WCS as needed.

For WCS linking, the “fast approximation” option uses an affine transform to represent the offset between images, if possible. It is much more performant at the cost of accuracy but should be accurate to within a pixel for most cases. If approximation fails, WCS linking still automatically falls back to full transformation.

Since Jdaviz v3.9, when linking by WCS, a hidden reference data layer without distortion (labeled “Default orientation”) will be created and all the data would be linked to it instead of the first loaded data. As a result, working in pixel space when linked by WCS is not recommended. Additionally, any data with distorted WCS would show as distorted on the display. Furthermore, any data without WCS can no longer be shown in WCS linking mode.

For the best experience, it is recommended that you decide what kind of link you want and set it at the beginning of your Imviz session, rather than later.

For more details on linking, see Linking of datasets in glue.

From the API#

From the API within the Jupyter notebook (if linking by WCS):

imviz.link_data(link_type='wcs')

Orientation: Image Rotation#

When linked by WCS, sky rotation is also possible. You can choose from presets (N-up, E-left/right) or provide your own sky angle.

Warning

Each rotation request created a new reference data layer in the background. Just as in Importing Data into Imviz, the performance would be impacted by the number of active rotation layers you have; Only keep the desired rotation layer. Note that the “default orientation” layer cannot be removed.

Compass#

For an image with a valid WCS, the compass will show directions to North (N) and East (E) for ICRS sky coordinates. It also shows the currently displayed data label, the X and Y directions, and the zoom box.

Note that when the axes canvas is rotated (by Canvas Rotation), the zoom box corresponds to the set zoom limits, not the extent of the viewer. Instead, the compass image itself is shown rotated/flipped to the same orientation.

When you have multiple viewers created in Imviz, use the Viewer dropdown menu to change the active viewer that it tracks.

Line Profiles#

This plugin plots line profiles across X and Y for the pixel under cursor when l key is pressed on the image viewer. You can also manually type in the values of X and Y, and then press the PLOT button. The top visible image, the same one displayed under Compass, will be used for these plots.

This plugin only considers pixel locations, not sky coordinates.

Aperture Photometry#

Warning

Regardless of your workflow, any WCS distortion in an image is ignored.

This plugin performs simple aperture photometry and plots a radial profile for one object within an interactively selected region. A typical workflow is as follows:

  1. Load image(s) in Imviz (see Importing Data into Imviz).

  2. Draw a region over the object of interest (see Defining Spatial Regions).

  3. Select the desired image using the Data dropdown menu.

  4. Select the desired region using the Subset dropdown menu. You can use the Subset Tools plugin to center it first on the object of interest using its center of mass, if you wish. Depending on the object, it may take several iterations for re-centering to converge, or it may never converge at all.

    Note

    You cannot use annulus region as aperture (an exception will be thrown) but you may use it for background (see below).

  5. If you want to subtract background before performing photometry, you have the following 3 options. Otherwise if your image is already background subtracted, choose “Manual” and leave the background set at 0:

  • Manual: Enter the background value in the Background value field. This value must be in the same unit as display data, if applicable.

  • Subset: Define a region for background calculation (median) using Subset draw tool and select that region using the Background dropdown menu. Only regions created with the replace option are acceptable as background regions (see Defining Spatial Regions).

  1. For some JWST and HST images, pixel area in arcsec squared is automatically populated in the Pixel area field from image metadata. If it does not auto-populate for you, you can manually enter a value but it must be in the unit of arcsec squared. This field is only used if per steradian is detected in display data unit. Otherwise, it is only informational. If this field is not applicable for you, leave it at 0. This field resets every time Data selection changes if auto-population not possible.

    Warning

    If your data is in surface brightness units and pixels on the image have varying sky area, you should first convert your data from surface brightness to flux units before using this plugin. This is because, for performance reasons, the plugin multiplies by the area after the aperture sum is calculated.

  2. If you also want photometry result in the unit of counts, you can enter a conversion factor in the Counts conversion factor field. The value must be in the unit of display data unit per counts. This is used to convert linear flux unit (e.g., MJy/sr) to counts. This field is only used if data has a valid unit. If this field is not applicable for you, leave it at 0. This field resets every time Data selection changes.

  3. If you also want photometry result in magnitude unit, you can enter a flux scaling factor in the Flux scaling field. Flux scaling is populated for JWST images if MJy/sr data unit is detected and pixel area is given to factor out the per-steradian unit. The value used, if this is the case, is the scaling to convert MJy to AB magnitude. Otherwise, the value must be in the same unit as display data unit. A magnitude is then calculated using -2.5 * log(flux / flux_scaling). This calculation only makes sense if your display data unit is already in linear flux unit. Setting this to 1 is equivalent to not applying any scaling. This field is only used if data has a valid unit. If this field is not applicable for you, leave it at 0. This field resets every time Data selection changes.

  4. Select the desired radial profile plot type using the Plot Type dropdown menu:

  • Curve of Growth: sum (sum of flux in the aperture) across radii from center out to the edge of the aperture. This is calculated in the same way as the final aperture sum in the output table, which is explained farther down on this page.

  • Radial Profile: Binned average as a function of radius from the center of the region.

  • Radial Profile (Raw): Raw image data points as a function of radius from the center of the region. Caution: having too many data points may cause performance issues with this feature. The exact limitations depend on your hardware.

  1. Toggle Fit Gaussian on to fit a Gaussian1D model to the radial profile data. This is disabled for curve-of-growth.

  2. Once all inputs are populated correctly, click on the CALCULATE button to perform simple aperture photometry.

Note

The shape you see drawn from Defining Spatial Regions is not exactly the aperture mask being used by photutils. This is because photutils uses fractional pixels and this is not reflected in the display.

Masking and weights by uncertainty are currently not supported. However, if NaN exists in data, it will be treated as 0.

When calculation is complete, a plot would show the radial profile of the background subtracted data and the photometry and model fitting (if requested) results are displayed under the CALCULATE button.

Imviz radial profile plot.

Radial profile.#

Imviz radial profile plot (raw).

Radial profile (raw).#

See also

Export Photometry

Documentation on exporting photometry results.

Footprints#

This plugin supports loading and overplotting instrument footprint overlays on the image viewers. Any number of overlays can be plotted simultaneously from any number of the available preset instruments (requires pysiaf to be installed) or by loading an Astropy regions object from a file.

The top dropdown allows renaming, adding, and removing footprint overlays. To modify the display and input parameters for a given overlay, select it in the dropdown, and modify the choices in the plugin to change its color, opacity, visibilities in any image viewer in the app, or to select between various preset instruments and change the input options (position on the sky, position angle, offsets, etc).

To import a file, choose “From File…” from the presets dropdown and select a valid file (must be able to be parsed by regions.Regions.read).

To import a regions file or object from the API:

fp = imviz.plugins['Footprints']
fp.open_in_tray()
fp.add_overlay('my imported overlay')  # or fp.rename_overlay to rename an existing entry
fp.import_region(region)

Canvas Rotation#

Note

This plugin is deprecated in favor of rotation via Orientation and will be removed in a future release.

The canvas rotation plugin allows rotating and horizontally flipping the image to any arbitrary value by rotating the canvas axes themselves. Note that this does not affect the underlying data, and exporting data to the notebook via the API will therefore not exhibit the same rotation.

The Compass will also rotate (and flip) accordingly, but will show the zoom box corresponding to the zoom limits, not the region shown in the viewer itself.

Presets are provided to reset the orientation as well as to set north up and east either to the right or the left, as well as a slider and input to set the angle and a switch to set whether the axes should be flipped horizontally after applying the rotation (a vertical flip can be achieved via a 180 deg rotation and a horizontal flip).

Due to browser limitations, Canvas Rotation is only available on Chromium-based browsers.

Export#

This plugin allows exporting:

  • the plot in a given viewer to a PNG or SVG file,

  • a table in a plugin to ecsv

  • subsets as a region to .fits or .reg file.

On this page
Edit on GitHub