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=<photutils.background.interpolators.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 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 sizebox_size
will be used. Ifbox_size
has two elements, they must be in(ny, nx)
order. For best results, the box shape should be chosen such that thedata
are covered by an integer number of boxes in both dimensions. When this is not the case, see theedge_method
keyword for more options.- maskarray_like (bool), optional
A boolean mask, with the same shape as
data
, where aTrue
value indicates the corresponding element ofdata
is masked. Masked data are excluded from calculations.mask
is intended to mask sources or bad pixels. Usecoverage_mask
to mask blank areas of an image.mask
andcoverage_mask
differ only in thatcoverage_mask
is applied to the output background and background RMS maps (seefill_value
).- coverage_maskarray_like (bool), optional
A boolean mask, with the same shape as
data
, where aTrue
value indicates the corresponding element ofdata
is masked.coverage_mask
should beTrue
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 usemask
instead).mask
andcoverage_mask
differ only in thatcoverage_mask
is applied to the output background and background RMS maps (seefill_value
).- fill_valuefloat, optional
The value used to fill the output background and background RMS maps where the input
coverage_mask
isTrue
.- 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 inputmask
andcoverage_mask
, those resulting from the data padding (i.e., ifedge_method='pad'
), and those resulting from sigma clipping (ifsigma_clip
is used). Settingexclude_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 sizefilter_size
will be used. Iffilter_size
has two elements, they must be in(ny, nx)
order.filter_size
must be odd along both axes. A filter size of1
(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 toNone
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 ofbox_size
in both dimensions.'pad'
: pad the image along the top and/or right edges. This is the default and recommended method. Ideally, thebox_size
should be chosen such that an integer number of boxes is only slightly larger than thedata
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 whenbox_size
is chosen such that an integer number of boxes is only slightly smaller than thedata
size to minimize the amount of cropping.
- sigma_clip
astropy.stats.SigmaClip
instance, optional A
SigmaClip
object that defines the sigma clipping parameters. IfNone
then no sigma clipping will be performed. The default is to perform sigma clipping withsigma=3.0
andmaxiters=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 2Dndarray
orMaskedArray
and have anaxis
keyword. Internally, the background will be calculated alongaxis=1
and in this case the callable object must return a 1Dndarray
, where np.nan values are used for masked pixels. Ifbkg_estimator
includes sigma clipping, it will be ignored (use thesigma_clip
keyword here to define sigma clipping). The default is an instance ofSExtractorBackground
.- 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 2Dndarray
orMaskedArray
and have anaxis
keyword. Internally, the background RMS will be calculated alongaxis=1
and in this case the callable object must return a 1Dndarray
, where np.nan values are used for masked pixels. Ifbkgrms_estimator
includes sigma clipping, it will be ignored (use thesigma_clip
keyword here to define sigma clipping). The default is an instance ofStdBackgroundRMS
.- 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 thescipy.ndimage.zoom
function.
- dataarray_like or
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) thedata
), then the background map will simply be a constant image.Attributes Summary
A 2D
ndarray
containing the background image.The median value of the 2D low-resolution background map.
The low-resolution background image.
The background 2D (masked) array mesh prior to any interpolation.
A 2D
ndarray
containing the background RMS image.The median value of the low-resolution background RMS map.
The low-resolution background RMS image.
The background RMS 2D (masked) array mesh prior to any interpolation.
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_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_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)[source]¶
Plot the low-resolution mesh boxes on a matplotlib Axes instance.
- Parameters:
- ax
matplotlib.axes.Axes
orNone
, optional The matplotlib axes on which to plot. If
None
, then the currentAxes
instance is used.- markerstr, optional
The marker to use to mark the center of the boxes. Default is ‘+’.
- markersize: float, optional
The marker size in points**2. 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 markers and the box outlines. Default is ‘blue’.
- alphafloat, optional
The alpha blending value, between 0 (transparent) and 1 (opaque). The blending applies to both the box center markers and the outlines.
- outlinesbool, optional
Whether or not to plot the box outlines in addition to the box centers.
- **kwargs
dict
Any keyword arguments accepted by
matplotlib.patches.Patch
. Used only ifoutlines
is True.
- ax