Background2D#

class photutils.background.Background2D(data, box_size, *, mask=None, coverage_mask=None, fill_value=0.0, exclude_percentile=10.0, filter_size=(3, 3), filter_threshold=None, sigma_clip=<default: SigmaClip(sigma=3.0, maxiters=10)>, bkg_estimator=None, bkg_rms_estimator=None, interpolator=None)[source]#

Bases: object

Class to estimate a 2D background and background RMS noise in an image.

The background is estimated using (sigma-clipped) statistics in each box of a grid that covers the input data to create a low-resolution, and possibly irregularly-gridded, background map.

The final background map is calculated by interpolating the low-resolution background map.

Invalid data values (i.e., NaN or inf) are automatically masked.

Note

Better performance will generally be obtained if you have the Bottleneck package installed. See Performance Tips for details, including notes on array byte order (endianness) when loading FITS data.

Parameters:

dataarray_like or NDData: The 2D array from which to estimate the background and/or background RMS map.
box_sizeint or array_like (int): The box size along each axis. If box_size is a scalar then a square box of size box_size will be used. If box_size has two elements, they must be in (ny, nx) order. For best results, the box shape should be chosen such that the data are covered by an integer number of boxes in both dimensions. When this is not the case, the image will be padded along the top and/or right edges. Ideally, the box_size should be chosen such that an integer number of boxes is only slightly larger than the data size to minimize the amount of padding.
maskarray_like (bool), optional: A boolean mask, with the same shape as data, where a True value indicates the corresponding element of data is masked. Masked data are excluded from the background and background RMS calculations. mask is intended to mask sources or bad pixels, but a background and background RMS value will be calculated for them based on interpolation of the low-resolution background and background RMS maps. Use coverage_mask to mask blank areas of an image. coverage_mask pixels are assigned a value of fill_value (default = 0) in the output background and background RMS maps.
coverage_maskarray_like (bool), optional: A boolean mask, with the same shape as data, where a True value indicates the corresponding element of data is masked. coverage_mask should be True where there is no coverage (i.e., no data) for a given pixel (e.g., blank areas in a mosaic image). It should not be used to mask sources or bad pixels (in that case use mask instead). coverage_mask pixels are assigned a value of fill_value (default = 0) in the output background and background RMS maps.
fill_valuefloat, optional: The value used to fill the output background and background RMS maps where the input coverage_mask is True.
exclude_percentilefloat in the range of [0, 100], optional: The percentage of masked pixels allowed in a box for it to be included in the low-resolution map. If a box has more than exclude_percentile percent of its pixels masked then it will be excluded from the low-resolution map. Masked pixels include those from the input mask and coverage_mask, non-finite data values, any padded area at the data edges, and those resulting from any sigma clipping. Setting exclude_percentile=0 will exclude boxes that have any that have any masked pixels. Note that completely masked boxes are always excluded. In general, exclude_percentile should be kept as low as possible to ensure there are a sufficient number of unmasked pixels in each box for reasonable statistical estimates. The default is 10.0.
filter_sizeint or array_like (int), optional: The window size of the 2D median filter to apply to the low-resolution background map. If filter_size is a scalar then a square box of size filter_size will be used. If filter_size has two elements, they must be in (ny, nx) order. filter_size must be odd along both axes. A filter size of 1 (or (1, 1)) means no filtering.
filter_thresholdint, optional: The threshold value for used for selective median filtering of the low-resolution 2D background map. The median filter will be applied to only the background boxes with values larger than filter_threshold. Set to None to filter all boxes (default).
sigma_clipastropy.stats.SigmaClip or None, optional: A SigmaClip object that defines the sigma clipping parameters. If None then no sigma clipping will be performed.
bkg_estimatorcallable, optional: A callable object (a function or e.g., an instance of any BackgroundBase subclass) used to estimate the background in each of the boxes. The callable object must take in a 2D ndarray or MaskedArray and have an axis keyword. Internally, the background will be calculated along axis=1 and in this case the callable object must return a 1D ndarray, where np.nan values are used for masked pixels. If bkg_estimator includes sigma clipping, it will be ignored (use the sigma_clip keyword here to define sigma clipping). The default is an instance of SExtractorBackground.
bkg_rms_estimatorcallable, optional: A callable object (a function or e.g., an instance of any BackgroundRMSBase subclass) used to estimate the background RMS in each of the boxes. The callable object must take in a 2D ndarray or MaskedArray and have an axis keyword. Internally, the background RMS will be calculated along axis=1 and in this case the callable object must return a 1D ndarray, where np.nan values are used for masked pixels. If bkg_rms_estimator includes sigma clipping, it will be ignored (use the sigma_clip keyword here to define sigma clipping). The default is an instance of StdBackgroundRMS.
interpolatorcallable, optional: A callable object (a function or object) used to interpolate the low-resolution background or background RMS image to the full-size background or background RMS maps. The default is an instance of BkgZoomInterpolator, which uses the scipy.ndimage.zoom function.

Deprecated since version 3.0: This keyword argument is deprecated and will be removed in a future version. When removed, the scipy.ndimage.zoom cubic spline interpolator will always be used to resize the low-resolution background and background RMS arrays to the full image size.

Notes

Integer input data produce background and background RMS outputs with np.float32 dtype to preserve precision from interpolation while minimizing memory usage. Float input data produce background and background RMS outputs with the same dtype as the input data.

If there is only one background box element (i.e., box_size is the same size as (or larger than) the data), then the background map will simply be a constant image.

Attributes Summary

`background`	A 2D `ndarray` containing the background image.
`background_median`	The median value of the 2D low-resolution background map.
`background_mesh`	The low-resolution background image.
`background_rms`	A 2D `ndarray` containing the background RMS image.
`background_rms_median`	The median value of the low-resolution background RMS map.
`background_rms_mesh`	The low-resolution background RMS image.
`n_pixels_map`	A 2D map of the number of pixels used to compute the statistics in each mesh, resized to the shape of the input image.
`n_pixels_mesh`	A 2D array of the number pixels used to compute the statistics in each mesh.
`npixels_map`
`npixels_mesh`

Methods Summary

plot_meshes(*[, ax, marker, markersize, ...])

Plot the low-resolution mesh boxes on a matplotlib Axes instance.

Attributes Documentation

background#: A 2D ndarray containing the background image.

Note

The returned image is (re)calculated each time this property is accessed. Store the result in a variable if you need to access it more than once.

background_median#

The median value of the 2D low-resolution background map.

This is equivalent to the value SourceExtractor prints to stdout (i.e., “(M+D) Background: <value>”).

Note

This value is computed over the full background_mesh, which includes IDW-interpolated values for any mesh boxes that were excluded from the statistics (e.g., due to masking or exclude_percentile). It therefore represents the median of the final interpolated mesh, not solely the median of directly measured mesh values.

background_mesh#

The low-resolution background image.

This image is equivalent to the low-resolution “MINIBACK” background map check image in SourceExtractor.

background_rms#: A 2D ndarray containing the background RMS image.

Note

The returned image is (re)calculated each time this property is accessed. Store the result in a variable if you need to access it more than once.

background_rms_median#

The median value of the low-resolution background RMS map.

This is equivalent to the value SourceExtractor prints to stdout (i.e., “(M+D) RMS: <value>”).

Note

This value is computed over the full background_rms_mesh, which includes IDW-interpolated values for any mesh boxes that were excluded from the statistics (e.g., due to masking or exclude_percentile). It therefore represents the median of the final interpolated mesh, not solely the median of directly measured mesh values.

background_rms_mesh#

The low-resolution background RMS image.

This image is equivalent to the low-resolution “MINIBACK_RMS” background rms map check image in SourceExtractor.

n_pixels_map#: A 2D map of the number of pixels used to compute the statistics in each mesh, resized to the shape of the input image.

Note

The returned image is (re)calculated each time this property is accessed. Store the result in a variable if you need to access it more than once.

n_pixels_mesh#: A 2D array of the number pixels used to compute the statistics in each mesh.

npixels_map#: Deprecated since version 3.0: This function was deprecated in version 3.0 and will be removed in version 4.0. Use n_pixels_map instead.

A 2D map of the number of pixels used to compute the statistics in each mesh, resized to the shape of the input image.

Deprecated since version 3.0: Use n_pixels_map instead.

Note

The returned image is (re)calculated each time this property is accessed. Store the result in a variable if you need to access it more than once.

npixels_mesh#: Deprecated since version 3.0: This function was deprecated in version 3.0 and will be removed in version 4.0. Use n_pixels_mesh instead.

A 2D array of the number pixels used to compute the statistics in each mesh.

Deprecated since version 3.0: Use n_pixels_mesh instead.

Methods Documentation

plot_meshes(*, ax=None, marker='+', markersize=None, color='blue', alpha=None, outlines=False, **kwargs)[source]#

Plot the low-resolution mesh boxes on a matplotlib Axes instance.

Parameters:

axmatplotlib.axes.Axes or None, optional: The matplotlib axes on which to plot. If None, then the current Axes instance is used.
markerstr, optional: The matplotlib marker to use to mark the center of the boxes.
markersizefloat, optional: The box center marker size in points ** 2 (typographical points are 1/72 inch) . The default is matplotlib.rcParams['lines.markersize'] ** 2. If set to 0, then the box center markers will not be plotted.
colorstr, optional: The color for the box center markers and outlines.
alphafloat, optional: The alpha blending value, between 0 (transparent) and 1 (opaque), for the box center markers and outlines.
outlinesbool, optional: Whether or not to plot the box outlines.
**kwargsdict, optional: Any keyword arguments accepted by matplotlib.patches.Patch, which is used to draw the box outlines. Used only if outlines is True.