calc_total_error¶
- photutils.utils.calc_total_error(data, bkg_error, effective_gain)[source]¶
Calculate a total error array, 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 asdata
. Ifdata
andbkg_error
areQuantity
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. 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 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 thedata
. A 2Deffective_gain
image is useful when the inputdata
has variable depths across the field (e.g., a mosaic image with non-uniform exposure times). For example, if your inputdata
are in units of electrons/s then ideallyeffective_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 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)}\]