Fix wavelet output files

bdsf/wavelet_atrous.py

@@ -120,7 +120,7 @@ def __call__(self, img):
                 else:
                     w = im_old - im_new
                 im_old = im_new
-                suffix = 'w' + repr(j)
+                suffix = ('remaining' if img.opts.atrous_sum else 'w') + repr(j)
                 filename = img.imagename + '.atrous.' + suffix + '.fits'
                 if img.opts.output_all:
                     func.write_image_to_file('fits', filename, w, img, bdir)
@@ -307,16 +307,27 @@ def __call__(self, img):
 
             img.total_flux_gaus += total_flux
             mylogger.userinfo(mylog, "Total flux density in model on all scales", '%.3f Jy' % img.total_flux_gaus)
+
             if img.opts.output_all:
+                # Save the final low-pass (cJ) image.
                 func.write_image_to_file('fits', img.imagename + '.atrous.cJ.fits',
-                                         im_new, img, bdir)
+                                        im_new, img, bdir)
                 mylog.info('%s %s' % ('Wrote ', img.imagename + '.atrous.cJ.fits'))
+
+                # Save the final residual after both standard and wavelet Gaussian fitting.
                 func.write_image_to_file('fits', img.imagename + '.resid_wavelets.fits',
-                                         (img.ch0_arr - img.resid_gaus_arr + img.resid_wavelets_arr), img, bdir + '/residual/')
+                                        img.resid_wavelets_arr, img, bdir + '/residual/')
                 mylog.info('%s %s' % ('Wrote ', img.imagename + '.resid_wavelets.fits'))
+
+                # Save the complete model: standard Gaussian model + wavelet Gaussian model.
                 func.write_image_to_file('fits', img.imagename + '.model_wavelets.fits',
-                                         (img.resid_gaus_arr - img.resid_wavelets_arr), img, bdir + '/model/')
+                                        (img.ch0_arr - img.resid_wavelets_arr), img, bdir + '/model/')
                 mylog.info('%s %s' % ('Wrote ', img.imagename + '.model_wavelets.fits'))
+
+                # Save the additional model contributed by wavelet Gaussian fitting only.
+                func.write_image_to_file('fits', img.imagename + '.model_wavelets_component.fits',
+                                        (img.resid_gaus_arr - img.resid_wavelets_arr), img, bdir + '/model/')
+                mylog.info('%s %s' % ('Wrote ', img.imagename + '.model_wavelets_component.fits'))
             img.completed_Ops.append('wavelet_atrous')
 
     def atrous(self, image, filtvec, lpf, j, numcores=1):

doc/source/process_image.rst

@@ -950,9 +950,20 @@ The wavelet module performs the following steps:
 
 * For each scale (*j*), the appropriate *à trous* wavelet transformation is made (see Holschneider et al. 1989 for details). Additionally, the "remainder" image (called the *c_J* image) is also made. This image includes all emission not included in the other wavelet images.
 
-* Depending on the value of the ``atrous_sum`` option, fitting is done to either an image that is a sum over all scales equal to or larger than the scale under consideration (``atrous_sum = True``) or to an image of a single scale (``atrous_sum = False``). Fitting to the sum over all larger scales will generally result in increased signal to noise.
+* Depending on the value of the `atrous_sum` option, fitting is
+  done either to the remaining-scale image (`atrous_sum = True`)
+  or to an individual wavelet scale (`atrous_sum = False`).
+  Fitting to the remaining-scale image generally results in
+  increased signal to noise.
 
-* If ``atrous_bdsm = True``, an rms map and a mean map are made for each wavelet image and Gaussians are fit in the normal way. Gaussians can be optionally restricted to lie within islands found from the initial image. If a wavelet island overlaps spatially with an existing island, the two islands are merged together to form a single island. The wavelet Gaussians can then be included in source catalogs (see :ref:`write_catalog`).
+  When `atrous_sum = True`, the remaining-scale image includes
+  emission from the current and larger wavelet scales, with
+  contributions from previously fitted wavelet Gaussians removed.
+  When `atrous_sum = False`, fitting is performed on the individual
+  wavelet component, calculated as the difference between two
+  consecutive low-pass images.
+
+* If ``atrous_bdsm_do = True``, an rms map and a mean map are made for each wavelet image and Gaussians are fit in the normal way. Gaussians can be optionally restricted to lie within islands found from the initial image. If a wavelet island overlaps spatially with an existing island, the two islands are merged together to form a single island. The wavelet Gaussians can then be included in source catalogs (see :ref:`write_catalog`).
 
 The options for this module are as follows:
 
@@ -1002,6 +1013,34 @@ The options for this module are as follows:
         This parameter is a Boolean (default is ``True``). If ``True``, fitting is done on an image that is the sum of the remaining wavelet scales. Using the sum will generally result in improved signal.
         If ``False``, fitting is done on only the wavelet scale under consideration.
 
+
+Wavelet output images
+---------------------
+
+If `output_all = True`, the wavelet module writes the following
+FITS images to the `wavelet` output directory:
+
+* `*.atrous.wJ.fits`: Individual wavelet component at scale J,
+  when `atrous_sum = False`.
+
+* `*.atrous.remainingJ.fits`: Remaining-scale image used for
+  Gaussian fitting at scale J, when `atrous_sum = True`.
+
+* `*.atrous.cJ.fits`: Final low-pass (remainder) image after
+  the wavelet decomposition.
+
+* `model/*.model_wavelets.fits`: Complete source model,
+  including both the standard Gaussian model and the additional
+  wavelet Gaussian model.
+
+* `model/*.model_wavelets_component.fits`: Additional model
+  contributed by wavelet Gaussian fitting only.
+
+* `residual/*.resid_wavelets.fits`: Final residual image after
+  subtraction of both the standard Gaussian model and the
+  wavelet Gaussian model.
+
+
 .. _psf_vary_do:
 
 PSF variation module