LocalBackground#

class photutils.background.LocalBackground(inner_radius, outer_radius, bkg_estimator=None, *, n_threads=1)[source]#

Bases: object

Class to compute a local background using a circular annulus aperture.

Parameters:

inner_radiusfloat: The inner radius of the circular annulus in pixels.
outer_radiusfloat: The outer radius of the circular annulus in pixels.
bkg_estimatorcallable, optional: A callable object (a function or e.g., an instance of any BackgroundBase subclass) used to estimate the background in each aperture. The callable object must take in a 1D ndarray or MaskedArray. The default is an instance of MedianBackground with sigma clipping (i.e., sigma-clipped median).
n_threadsint, optional: The number of threads to use to measure the local backgrounds. The default is 1 (no multithreading). The value is passed through to the internal ApertureStats computation, which divides the annulus positions into chunks that are processed concurrently, producing results identical to the single-threaded computation. Multithreading is used only for the standard photutils estimator classes (see bkg_estimator). A custom estimator callable uses the serial per-aperture loop.

Examples

>>> import numpy as np
>>> from photutils.background import LocalBackground
>>> data = np.ones((101, 101))
>>> local_bkg = LocalBackground(5, 10)
>>> bkg = local_bkg(data, 50, 50)
>>> print(bkg)
1.0

>>> # Multiple positions
>>> x = [30, 50, 70]
>>> y = [30, 50, 70]
>>> bkg = local_bkg(data, x, y)
>>> print(bkg)
[1. 1. 1.]

Methods Summary

`__call__`(data, x, y[, mask])	Measure the local background in a circular annulus.
`to_aperture`(x, y)	Return a `CircularAnnulus` instance representing the local background annulus at the given positions.

Methods Documentation

__call__(data, x, y, mask=None)[source]#

Measure the local background in a circular annulus.

Parameters:

data2D ndarray or Quantity: The 2D array on which to measure the local background.
x, yfloat or 1D float ndarray: The aperture center (x, y) position(s) at which to measure the local background.
mask2D bool ndarray, 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 all calculations.

Returns:

valuefloat or 1D float ndarray: The local background values. If data is a Quantity, the result is a Quantity with the same unit. If all pixels in an annulus are masked or outside the data bounds, the corresponding value will be NaN.

Examples

>>> import numpy as np
>>> from photutils.background import LocalBackground
>>> data = np.ones((101, 101))
>>> local_bkg = LocalBackground(5, 10)
>>> bkg = local_bkg(data, 50, 50)
>>> print(bkg)
1.0

>>> # Multiple positions
>>> bkg = local_bkg(data, [30, 50], [40, 60])
>>> print(bkg)
[1. 1.]

>>> # Position outside data returns NaN
>>> bkg = local_bkg(data, -50, -50)
>>> print(np.isnan(bkg))
True

to_aperture(x, y)[source]#

Return a CircularAnnulus instance representing the local background annulus at the given positions.

Parameters:

x, yfloat or 1D float ndarray: The aperture center (x, y) position(s) at which to create the annulus aperture.

Returns:

aperturesCircularAnnulus instance: The circular annulus aperture(s) at the given position(s).

Examples

>>> from photutils.background import LocalBackground
>>> local_bkg = LocalBackground(5, 10)
>>> aperture = local_bkg.to_aperture(50, 50)
>>> aperture
<CircularAnnulus([[50., 50.]], r_in=5.0, r_out=10.0)>

>>> # Multiple positions
>>> aperture = local_bkg.to_aperture([30, 70], [40, 80])
>>> aperture
<CircularAnnulus([[30., 40.],
                  [70., 80.]], r_in=5.0, r_out=10.0)>
>>> print(len(aperture.positions))
2