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, edge_method='pad', sigma_clip=SigmaClip(sigma=3.0, sigma_lower=3.0, sigma_upper=3.0, maxiters=10, cenfunc='median', stdfunc='std', grow=False), bkg_estimator=SExtractorBackground(sigma_clip=None), bkgrms_estimator=StdBackgroundRMS(sigma_clip=None), interpolator=BkgZoomInterpolator(order=3, mode='reflect', cval=0.0, clip=True, grid_mode=True))[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. This acceleration also requires that the byte order of the input data array matches the byte order of the operating system. For example, the astropy.io.fits module loads data arrays as big-endian, even though most modern processors are little-endian. A big-endian array can be converted to native byte order (‘=’) in place using:

>>> data.byteswap(inplace=True)
>>> data = data.view(data.dtype.newbyteorder('='))

One can also use, e.g.,:

>>> data = data.astype(float)

but this will temporarily create a new copy of the array in memory.

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, see the edge_method keyword for more options.

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 calculations. mask is intended to mask sources or bad pixels. Use coverage_mask to mask blank areas of an image. mask and coverage_mask differ only in that coverage_mask is applied to the output background and background RMS maps (see fill_value).

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 for bad pixels (in that case use mask instead). mask and coverage_mask differ only in that coverage_mask is applied to the output background and background RMS maps (see fill_value).

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).

edge_method{‘pad’, ‘crop’}, optional

This keyword will be removed in a future version and the default version of 'pad' will always be used. The 'crop' option has been strongly discouraged for some time now. Its usage creates a undesirable scaling of the low-resolution maps that leads to incorrect results.

The method used to determine how to handle the case where the image size is not an integer multiple of the box_size in either dimension. Both options will resize the image for internal calculations to give an exact multiple of box_size in both dimensions.

'pad': pad the image along the top and/or right edges. This is the default and recommended method. 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.
'crop': crop the image along the top and/or right edges. This method should be used sparingly, and it may be deprecated in the future. Best results will occur when box_size is chosen such that an integer number of boxes is only slightly smaller than the data size to minimize the amount of cropping.

sigma_clipastropy.stats.SigmaClip instance, optional

A SigmaClip object that defines the sigma clipping parameters. If None then no sigma clipping will be performed. The default is to perform sigma clipping with sigma=3.0 and maxiters=10.

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.

bkgrms_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 bkgrms_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.

Notes

Better performance will generally be obtained if you have the bottleneck package installed.

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_mesh_masked`
`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.
`background_rms_mesh_masked`
`mesh_nmasked`
`npixels_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.
`npixels_mesh`	A 2D array of the number pixels used to compute the statistics in each 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 that the returned value is (re)calculated each time this property is accessed. If you need to access the background image multiple times, you should store the result in a variable.

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>”).

background_mesh#

The low-resolution background image.

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

background_mesh_masked#

Deprecated since version 2.0.0: The background_mesh_masked function is deprecated and may be removed in a future version.

The low-resolution background image prior to any interpolation to fill NaN values.

The array has NaN values where meshes were excluded.

background_rms#

A 2D ndarray containing the background RMS image.

Note that the returned value is (re)calculated each time this property is accessed. If you need to access the background rms image multiple times, you should store the result in a variable.

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>”).

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.

background_rms_mesh_masked#

Deprecated since version 2.0.0: The background_rms_mesh_masked function is deprecated and may be removed in a future version.

The low-resolution background RMS image prior to any interpolation to fill NaN values.

The array has NaN values where meshes were excluded.

mesh_nmasked#

Deprecated since version 2.0.0: The mesh_nmasked function is deprecated and may be removed in a future version. Use npixels_mesh instead.

A 2D array of the number of masked pixels in each mesh.

NaN values indicate where meshes were excluded.

npixels_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 that the returned value is (re)calculated each time this property is accessed. If you need to access the returned image multiple times, you should store the result in a variable.

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

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.