Background2D

class photutils.Background2D(data, box_size, mask=None, exclude_percentile=10.0, filter_size=(3, 3), filter_threshold=None, edge_method=u'pad', sigma_clip=SigmaClip(sigma=3.0, sigma_lower=None, sigma_upper=None, iters=10, cenfunc=<function median>, stdfunc=<function std>), bkg_estimator=<photutils.background.core.SExtractorBackground object>, bkgrms_estimator=<photutils.background.core.StdBackgroundRMS object>, interpolator=<photutils.background.background_2d.BkgZoomInterpolator object>)[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 mesh 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.

Parameters:

data : array_like

The 2D array from which to estimate the background and/or background RMS map.

box_size : int 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 should 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.

mask : array_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.

exclude_percentile : float in the range of [0, 100], optional

The percentage of masked pixels in a mesh, used as a threshold for determining if the mesh is excluded. If a mesh 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, those resulting from the data padding (i.e. if edge_method='pad'), and those resulting from any sigma clipping (i.e. if sigma_clip is used). Setting exclude_percentile=0 will exclude meshes that have any masked pixels. Setting exclude_percentile=100 will only exclude meshes that are completely masked. Note that completely masked meshes 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.

filter_size : int 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 should be in (ny, nx) order. A filter size of 1 (or (1, 1)) means no filtering.

filter_threshold : int, 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 meshes with values larger than filter_threshold. Set to None to filter all meshes (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 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.
  • 'crop': crop the image along the top and/or right edges.

sigma_clip : astropy.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. and iters=10.

bkg_estimator : callable, optional

A callable object (a function or e.g., an instance of any BackgroundBase subclass) used to estimate the background in each of the meshes. 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). The callable object must return a 1D MaskedArray. If bkg_estimator includes sigma clipping, it will be ignored (use the sigma_clip keyword to define sigma clipping). The default is an instance of SExtractorBackground.

bkgrms_estimator : callable, 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 meshes. 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). The callable object must return a 1D MaskedArray. If bkgrms_estimator includes sigma clipping, it will be ignored (use the sigma_clip keyword to define sigma clipping). The default is an instance of StdBackgroundRMS.

interpolator : callable, optional

A callable object (a function or object) used to interpolate the low-resolution background or background RMS mesh to the full-size background or background RMS maps. The default is an instance of BkgZoomInterpolator.

Notes

If there is only one background mesh element (i.e., box_size is the same size as 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_ma 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_ma The background RMS 2D (masked) array mesh prior to any interpolation.
mesh_nmasked A 2D (masked) array of the number of masked pixels in each mesh.

Methods Summary

plot_meshes([ax, marker, color, outlines]) 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 SExtractor prints to stdout (i.e., “(M+D) Background: <value>”).

background_mesh_ma

The background 2D (masked) array mesh prior to any interpolation. The array is masked only if 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 SExtractor prints to stdout (i.e., “(M+D) RMS: <value>”).

background_rms_mesh_ma

The background RMS 2D (masked) array mesh prior to any interpolation. The array is masked only if meshes were excluded.

mesh_nmasked

A 2D (masked) array of the number of masked pixels in each mesh. Only meshes included in the background estimation are included. The array is masked only if meshes were excluded.

Methods Documentation

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

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

Parameters:

ax : matplotlib.axes.Axes instance, optional

If None, then the current Axes instance is used.

marker : str, optional

The marker to use to mark the center of the boxes. Default is ‘+’.

color : str, optional

The color for the markers and the box outlines. Default is ‘blue’.

outlines : bool, optional

Whether or not to plot the box outlines in addition to the box centers.

kwargs

Any keyword arguments accepted by matplotlib.patches.Patch. Used only if outlines is True.