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, grid_mode=True, clip=True))

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.

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 in a box, used as a threshold for determining if the box is excluded. 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, those resulting from the data padding (i.e., if edge_method='pad'), and those resulting from sigma clipping (if sigma_clip is used). Setting exclude_percentile=0 will exclude boxes that have any masked pixels. Note that completely masked boxes are always excluded. For best results, exclude_percentile should be kept as low as possible (as long as there are sufficient pixels 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

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. 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	The background 2D (masked) array mesh prior to any interpolation.
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	The background RMS 2D (masked) array mesh prior to any interpolation.
mesh_nmasked	A 2D array of the number of masked pixels 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.

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 “MINIBACKGROUND” background map in SourceExtractor.

background_mesh_masked

The background 2D (masked) array mesh prior to any interpolation. The array has NaN values where meshes were excluded.

background_rms

A 2D ndarray containing the background RMS image.

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 “MINIBACKGROUND” background rms map in SourceExtractor.

background_rms_mesh_masked

The background RMS 2D (masked) array mesh prior to any interpolation. The array has NaN values where meshes were excluded.

mesh_nmasked

A 2D array of the number of masked pixels in each mesh. NaN values indicate where meshes were excluded.

Methods Documentation

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

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

Any keyword arguments accepted by matplotlib.patches.Patch, which is used to draw the box outlines. Used only if outlines is True.