Merge pull request #938 from pllim/one-hour-photometry-no-photutils

Imviz simple aperture photometry plugin (no photutils)

CHANGES.rst

@@ -15,6 +15,8 @@ Imviz
 
 - New plugin to control image linking via GUI. [#909]
 
+- New plugin to perform simple aperture photometry. [#938]
+
 Mosviz
 ^^^^^^
 
@@ -56,6 +58,9 @@ Imviz
 - ``imviz.get_interactive_regions()`` no longer produces long traceback
   for unsupported region shapes. [#906]
 
+- Imviz now parses some image metadata into ``glue`` and understands
+  ELECTRONS and ELECTRONS/S defined in FITS BUNIT header keyword. [#938]
+
 Mosviz
 ^^^^^^
 

docs/conf.py

@@ -242,6 +242,7 @@
 # Extra intersphinx in addition to what is already in sphinx-astropy
 intersphinx_mapping['glue'] = ('http://docs.glueviz.org/en/stable/', None)
 intersphinx_mapping['glue_jupyter'] = ('https://glue-jupyter.readthedocs.io/en/stable/', None)
+intersphinx_mapping['regions'] = ('https://astropy-regions.readthedocs.io/en/stable/', None)
 intersphinx_mapping['skimage'] = ('https://scikit-image.org/docs/stable/', None)
 intersphinx_mapping['specutils'] = ('https://specutils.readthedocs.io/en/stable/', None)
 intersphinx_mapping['spectral_cube'] = ('https://spectral-cube.readthedocs.io/en/stable/', None)

docs/dev/links.rst

@@ -1,3 +1,5 @@
+.. _dev_glue_linking:
+
 ***************************
 Linking of datasets in glue
 ***************************

docs/imviz/displayimages.rst

@@ -14,7 +14,6 @@ Selecting Data Set
     :ref:`Selecting Data Set<cubeviz-selecting-data>`
         Documentation on selecting data sets in the Jdaviz viewers.
 
-
 Adding New Viewers
 ==================
 
@@ -23,6 +22,8 @@ that when clicked will add new viewers to the application. You can then select f
 that has been loaded into the application to be visualized in these additional viewers.
 You can then utilize some of the Imviz-specific features, like :ref:`imviz_pan_zoom`.
 
+.. _imviz_defining_spatial_regions:
+
 Defining Spatial Regions
 ========================
 

docs/imviz/import_data.rst

@@ -30,4 +30,11 @@ notebook, you have access to the Imviz helper class API. Using this API,
 users can load data into the application through code using the :meth:`~jdaviz.configs.imviz.helper.Imviz.load_data`
 method, which takes as input either the name of a local file, an
 :class:`~astropy.nddata.NDData`, :class:`~astropy.io.fits.HDUList`,
-or :class:`~astropy.io.fits.ImageHDU` object.
+or :class:`~astropy.io.fits.ImageHDU` object.
+
+The example below loads the first science extension of the given FITS file into Imviz::
+
+    from jdaviz import Imviz
+    imviz = Imviz()
+    imviz.app
+    imviz.load_data("/path/to/data/image.fits")

docs/imviz/plugins.rst

@@ -4,4 +4,135 @@
 Data Analysis Plugins
 *********************
 
-Currently there are no active plugins that work with Imviz.
+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.
+
+.. _imviz-link-control:
+
+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`.
+
+
+.. _aper-phot-simple:
+
+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`.

jdaviz/configs/imviz/helper.py

@@ -279,6 +279,18 @@ def _delete_all_regions(self):
         for subset_grp in self.app.data_collection.subset_groups:  # should be a copy
             self.app.data_collection.remove_subset_group(subset_grp)
 
+    def get_aperture_photometry_results(self):
+        """Return aperture photometry results, if any.
+        Results are calculated using :ref:`aper-phot-simple` plugin.
+
+        Returns
+        -------
+        results : `~astropy.table.QTable` or `None`
+            Photometry results if available or `None` otherwise.
+
+        """
+        return getattr(self.app, '_aper_phot_results', None)
+
 
 def split_filename_with_fits_ext(filename):
     """Split a ``filename[ext]`` input into filename and FITS extension.

jdaviz/configs/imviz/imviz.yaml

@@ -19,6 +19,7 @@ toolbar:
   - g-coords-info
 tray:
   - imviz-links-control
+  - imviz-aper-phot-simple
 viewer_area:
   - container: col
     children:

jdaviz/configs/imviz/plugins/__init__.py

@@ -4,3 +4,4 @@
 from .parsers import *  # noqa
 from .coords_info import *  # noqa
 from .links_control import *  # noqa
+from .aper_phot_simple import *  # noqa

jdaviz/configs/imviz/plugins/aper_phot_simple/__init__.py

@@ -0,0 +1 @@
+from .aper_phot_simple import *  # noqa