calc_total_error¶

photutils.utils.
calc_total_error
(data, bkg_error, effective_gain)[source]¶ Calculate a total error array, combining a backgroundonly error array with the Poisson noise of sources.
 Parameters
 dataarray_like or
Quantity
The backgroundsubtracted data array.
 bkg_errorarray_like or
Quantity
The 1sigma backgroundonly 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 asdata
. Ifdata
andbkg_error
areQuantity
objects, then they must have the same units. effective_gainfloat, arraylike, or
Quantity
Ratio of counts (e.g., electrons or photons) to the units of
data
used to calculate the Poisson error of the sources. Ifeffective_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 thebkg_error
value for pixels whereeffective_gain
is zero.effective_gain
cannot not be negative or contain negative values.
 dataarray_like or
 Returns
Notes
To use units,
data
,bkg_error
, andeffective_gain
must all beQuantity
objects.data
andbkg_error
must have the same units. AValueError
will be raised if only some of the inputs areQuantity
objects or if thedata
andbkg_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 thedata
image.The total error is the combination of the backgroundonly 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 backgroundonly 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 thedata
. A 2Deffective_gain
image is useful when the inputdata
has variable depths across the field (e.g., a mosaic image with nonuniform exposure times). For example, if your inputdata
are in units of electrons/s then ideallyeffective_gain
should be an exposuretime 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 backgroundonly errors, and \(\mathrm{RMS_{\mathrm{median}}}\) is the median value of the lowresolution 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 lowresolution background RMS map is returned via thebackground_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)}\]