Skip to content

Latest commit

 

History

History
138 lines (118 loc) · 7.22 KB

plugins.rst

File metadata and controls

138 lines (118 loc) · 7.22 KB
Raw

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 :guilabel:`plugin` icon in the upper right corner of the Imviz application.

Link Control

This plugin is used to re-link images by pixels or WCS using :func:`~jdaviz.configs.imviz.helper.link_image_data`. All images are automatically linked by pixels on load but you can use it to re-link by pixels or WCS as needed. Once you have set your options, click :guilabel:`LINK` to perform the linking.

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.

For more details on linking, see :ref:`dev_glue_linking`.

Simple Aperture Photometry

This plugin performs simple aperture photometry on one object within an interactively selected region. A typical workflow is as follows:

  1. Load image(s) in Imviz (see :ref:`imviz-import-data`).
  2. Draw a region over the object of interest (see :ref:`imviz_defining_spatial_regions`).
  3. Select the desired image using :guilabel:`Data` drop-down menu.
  4. Select the desired region using :guilabel:`Subset` drop-down menu.
  5. If you want to subtract background before performing photometry, enter the background value in the :guilabel:`Background value` field. This value must be in the same unit as display data, if applicable. If your image is already background subtracted, leave it at 0.
  6. For some JWST and HST images, pixel area in arcsec squared is automatically populated in the :guilabel:`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.
  7. If you also want photometry result in the unit of counts, you can enter a conversion factor in the :guilabel:`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. If this field is not applicable for you, leave it at 0. This field resets every time Data selection changes.
  8. If you also want photometry result in magnitude unit, you can enter a flux scaling factor in the :guilabel:`Flux scaling` field. 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. If this field is not applicable for you, leave it at 0. This field resets every time Data selection changes.
  9. Once all inputs are populated correctly, click on the :guilabel:`CALCULATE` button to perform simple aperture photometry.

Note

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, the results are displayed under the :guilabel:`CALCULATE` button. You can also retrieve the results as ~astropy.table.QTable as follows, assuming imviz is the instance of your Imviz application:

results = imviz.get_aperture_photometry_results()

When multiple calculations are done in the same session (e.g., calculating aperture photometry for the same region across different images or for different regions on the same image), imviz.get_aperture_photometry_results() will return all the calculations in the same table, if possible. However, if the newest result is incompatible with the existing ones (e.g., two images have very different units), only the newest is kept in the table. When you are unsure, save the results after each calculation as different variables in your Python session.

The output table contains the results you see in the plugin and then some. The columns are as follow:

  • id: ID number assigned to the row, starting from 1.
  • xcenter, ycenter: Pixel center of the region used. No re-centering w.r.t. flux distribution is done.
  • sky_center: ~astropy.coordinates.SkyCoord associated with xcenter and ycenter. If WCS is not available, this field is None.
  • background: The value from :guilabel:`Background value`, with unit attached.
  • npix: The number of pixels covered by the region. Partial coverage is reported as fraction.
  • aperture_sum: Sum of flux in the aperture. If per steradian is in input data unit, total pixel area covered in steradian is already multiplied here, if applicable, so there will be no per steradian in its unit. Otherwise, it has the same unit as input data. To calculate this, :meth:`regions.PixelRegion.to_mask` is used with mode='exact' except for rectangular region, where it is used with mode='subpixels' and subpixels=32. Values from aperture mask are extracted using :meth:`regions.RegionMask.get_values`.
  • pixarea_tot: If per steradian is in input data unit and pixel area is provided, this contains the total pixel area covered by the aperture in steradian. Otherwise, it is None.
  • aperture_sum_counts: This is the aperture sum converted to counts, if :guilabel:`Counts conversion factor` was set. Otherwise, it is None. This calculation is done without taking account of pixarea_tot, even when it is available.
  • aperture_sum_counts_err: This is the Poisson uncertainty (square root) for aperture_sum_counts. Other uncertainty factors like readnoise are not included. In the plugin, it is displayed within parenthesis next to the value for aperture_sum_counts, if applicable.
  • counts_fac: The value from :guilabel:`Counts conversion factor`, with unit attached, if applicable. Otherwise, it is None.
  • aperture_sum_mag: This is the aperture sum converted to magnitude, if :guilabel:`Flux scaling` was set. Otherwise, it is None. This calculation is done without taking account of pixarea_tot, even when it is available.
  • flux_scaling: The value from :guilabel:`Flux scaling`, with unit attached, if applicable. Otherwise, it is None.
  • mean, stddev, median, min, max: Basic statistics from all the pixels in the region. These are done using :meth:`regions.PixelRegion.to_mask` with mode='center', unlike aperture_sum. They are not related to the aperture photometry, but are only provided as supplemental information.
  • data_label: Data label of the image used.
  • subset_label: Subset label of the region used.
  • timestamp: Timestamp of when the photometry was performed as ~astropy.time.Time.

Once you have the results in a table, you can further manipulated them as documented in :ref:`astropy:astropy-table`.