calc_total_error

photutils.utils.calc_total_error(data, bkg_error, effective_gain)

Calculate a total error array by combining a background-only error array with the Poisson noise of sources.

Parameters:

dataarray_like or Quantity

The background-subtracted data array.

bkg_errorarray_like or Quantity

The 1-sigma background-only errors of the input data. bkg_error should include all sources of “background” error but exclude the Poisson error of the sources. bkg_error must have the same shape as data. If data and bkg_error are Quantity objects, then they must have the same units.

effective_gainfloat, array_like, or Quantity

Ratio of counts (e.g., electrons or photons) to the units of data used to calculate the Poisson error of the sources. If effective_gain is zero (or contains zero values in an array), then the source Poisson noise component will not be included. In other words, the returned total error value will simply be the bkg_error value for pixels where effective_gain is zero. effective_gain cannot not be negative or contain negative values.

Returns:

total_errorndarray or Quantity

The total error array. If data, bkg_error, and effective_gain are all Quantity objects, then total_error will also be returned as a Quantity object with the same units as the input data. Otherwise, a ndarray will be returned.

Notes

To use units, data, bkg_error, and effective_gain must all be Quantity objects. data and bkg_error must have the same units. A ValueError will be raised if only some of the inputs are Quantity objects or if the data and bkg_error units differ.

The source Poisson error in countable units (e.g., electrons or photons) is:

\[\sigma_{\mathrm{src}} = \sqrt{g_{\mathrm{eff}} I}\]

where \(g_{\mathrm{eff}}\) is the effective gain (effective_gain; image or scalar) and \(I\) is the data image.

The total error is the combination of the background-only error and the source Poisson error. The total error array \(\sigma_{\mathrm{tot}}\) in countable units (e.g., electrons or photons) is therefore:

\[\sigma_{\mathrm{tot}} = \sqrt{g_{\mathrm{eff}}^2 \sigma_{\mathrm{bkg}}^2 + g_{\mathrm{eff}} I}\]

where \(\sigma_{\mathrm{bkg}}\) is the background-only error image (bkg_error).

Converting back to the input data units gives:

\[\sigma_{\mathrm{tot}} = \frac{1}{g_{\mathrm{eff}}} \sqrt{g_{\mathrm{eff}}^2 \sigma_{\mathrm{bkg}}^2 + g_{\mathrm{eff}} I}\]

\[\sigma_{\mathrm{tot}} = \sqrt{\sigma_{\mathrm{bkg}}^2 + \frac{I}{g_{\mathrm{eff}}}}\]

effective_gain can either be a scalar value or a 2D image with the same shape as the data. A 2D effective_gain image is useful when the input data has variable depths across the field (e.g., a mosaic image with non-uniform exposure times). For example, if your input data are in units of electrons/s then ideally effective_gain should be an exposure-time map.

The Poisson noise component is not included in the output total error for pixels where data (\(I_i)\) is negative. For such pixels, \(\sigma_{\mathrm{tot}, i} = \sigma_{\mathrm{bkg}, i}\).

The Poisson noise component is also not included in the output total error for pixels where the effective gain (\(g_{\mathrm{eff}, i}\)) is zero. For such pixels, \(\sigma_{\mathrm{tot}, i} = \sigma_{\mathrm{bkg}, i}\).

To replicate SourceExtractor errors when it is configured to consider weight maps as gain maps (i.e., ‘WEIGHT_GAIN=Y’; which is the default), one should input an effective_gain calculated as:

\[g_{\mathrm{eff}}^{\prime} = g_{\mathrm{eff}} \left( \frac{\mathrm{RMS_{\mathrm{median}}^2}}{\sigma_{\mathrm{bkg}}^2} \right)\]

where \(g_{\mathrm{eff}}\) is the effective gain, \(\sigma_{\mathrm{bkg}}\) are the background-only errors, and \(\mathrm{RMS_{\mathrm{median}}}\) is the median value of the low-resolution background RMS map generated by SourceExtractor. When running SourceExtractor, this value is printed to stdout as “(M+D) RMS: <value>”. If you are using Background2D, the median value of the low-resolution background RMS map is returned via the background_rms_median attribute.

In that case the total error is:

\[\sigma_{\mathrm{tot}} = \sqrt{\sigma_{\mathrm{bkg}}^2 + \left(\frac{I}{g_{\mathrm{eff}}}\right) \left(\frac{\sigma_{\mathrm{bkg}}^2} {\mathrm{RMS_{\mathrm{median}}^2}}\right)}\]