JP-3757: Use squared drizzle coeffs for variance and error arrays

changes/8997.resample.rst

@@ -0,0 +1,2 @@
+Resample variance and error arrays using squared drizzle coefficients
+(error propagation).

docs/jwst/resample/arguments.rst

@@ -95,7 +95,7 @@ image.
     If `weight_type=ivm` (the default), the scaling value
     will be determined per-pixel using the inverse of the read noise
     (VAR_RNOISE) array stored in each input image. If the VAR_RNOISE array does
-    not exist, the variance is set to 1 for all pixels (equal weighting).
+    not exist, the weight is set to 1 for all pixels (equal weighting).
     If `weight_type=exptime`, the scaling value will be set equal to the
     measurement time (TMEASURE) found in the image header if available;
     if unavailable, the scaling will be set equal to the exposure time (EFFEXPTM).

docs/jwst/resample/main.rst

@@ -36,56 +36,18 @@ drizzling to create the output product.
 Error Propagation
 -----------------
 
-The error associated with each resampled pixel can in principle be derived
+The error associated with each resampled pixel is derived
 from the variance components associated with each input pixel, weighted by
-the square of the input user weights and the square of the overlap between
-the input and output pixels. In practice, the cdriz routine does not currently
-support propagating variance data alongside science images, so the output
-error cannot be precisely calculated.
-
-To approximate the error on a resampled pixel, the variance arrays associated
-with each input image are resampled individually, then combined with a weighted
-sum.  The process is:
-
-#. For each input image, take the square root of each of the read noise variance
-   array to make an error image.
-
-#. Drizzle the read noise error image onto the output WCS, with drizzle
-   parameters matching those used for the science data.
-
-#. Square the resampled read noise to make a variance array.
-
-   a. If the resampling `weight_type` is an inverse variance map (`ivm`), weight
-      the resampled variance by the square of its own inverse.
-
-   #. If the `weight_type` is the exposure time (`exptime`), weight the
-      resampled variance by the square of the exposure time for the image.
-
-#. Add the weighted, resampled read noise variance to a running sum across all
-   images.  Add the weights (unsquared) to a separate running sum across
-   all images.
-
-#. Perform the same steps for the Poisson noise variance and the flat variance.
-   For these components, the weight for the sum is either the resampled read
-   noise variance or else the exposure time.
-
-#. For each variance component (read noise, Poisson, and flat), divide the
-   weighted variance sum by the total weight, squared.
+the square of the input user weights, pixel scale ratio, and the square of
+the overlap between the input and output pixels. Essentially the code performs
+[propagation of uncertainty](https://en.wikipedia.org/wiki/Propagation_of_uncertainty)
+for each of the variance arrays in the input models.
 
 After each variance component is resampled and summed, the final error
 array is computed as the square root of the sum of the three independent
 variance components.  This error image is stored in the ``err`` attribute
 in the output data model or the ``'ERR'`` extension of the FITS file.
 
-It is expected that the output errors computed in this way will
-generally overestimate the true error on the resampled data.  The magnitude
-of the overestimation depends on the details of the pixel weights
-and error images.  Note, however, that drizzling error images produces
-a much better estimate of the output error than directly drizzling
-the variance images, since the kernel overlap weights do not need to be
-squared for combining error values.
-
-
 Context Image
 -------------