API/Reference

estimate_background(data;
    location=SourceExtractorBackground(),
    rms=StdRMS(),
    dims=:)

Perform scalar background estimation using the given estimators.

The value returned will be two values corresponding to the estimated background and the estimated background RMS. The dimensionality will depend on the dims keyword.

location and rms can be anything that is callable, for example median, or one of the estimators we provide in Background Estimators.

Examples

julia> data = ones(3, 5);

julia> bkg, bkg_rms = estimate_background(data)
(1.0, 0.0)

julia> using Statistics: median

julia> bkg, bkg_rms = estimate_background(data; location=median, rms=MADStdRMS())
(1.0, 0.0)

See Also

• Location Estimators, RMS Estimators

estimate_background(data, box_size;
    location=SourceExtractorBackground(),
    rms=StdRMS(),
    itp=ZoomInterpolator(box_size),
    edge_method=:pad,
    [filter_size])

Perform 2D background estimation using the given estimators mapped over windows of the data..

This function will estimate backgrounds in boxes of size box_size. When size(data) is not an integer multiple of the box size, there are two edge methods: :pad and :crop. The default is to pad (and is recommend to avoid losing image data). If box_size is an integer, the implicit shape will be square (eg. box_size=4 is equivalent to box_size=(4,4)).

For evaluating the meshes, each box will be passed into location to estimate the background and then into rms to estimate the background root-mean-square value. These can be anything that is callable, like median or one of our Background Estimators.

Once the meshes are created they will be median filtered if filter_size is given. filter_size can be either an integer or a tuple, with the integer being converted to a tuple the same way box_size is. Filtering is done via ImageFiltering.MapWindow.mapwindow. filter_size must be odd.

After filtering (if applicable), the meshes are passed to the itp to recreate a low-order estimate of the background at the same resolution as the input.

See Also

• Location Estimators, RMS Estimators, Interpolators

sigma_clip(x, sigma; fill=:clamp, center=median(x), std=std(x, corrected=false))
sigma_clip(x, sigma_low, sigma_high; fill=:clamp, center=median(x), std=std(x, corrected=false))

This function returns sigma-clipped values of the input x.

Specify the upper and lower bounds with sigma_low and sigma_high, otherwise assume they are equal. center and std are optional keyword arguments which are functions for finding central element and standard deviation.

If fill === :clamp, this will clamp values in x lower than center - sigma_low * std and values higher than center + sigma_high * std. Otherwise, they will be replaced with fill.

Examples

julia> x = randn(rng, 100_000); # rng is a pre-defined generator for reproducibility

julia> extrema(x)
(-4.308034628060624, 4.082248634424802)


julia> x_clip = sigma_clip(x, 1);

julia> extrema(x_clip) # should be close to (-1, 1)
(-0.9912911763341569, 1.0077955853440512)

sigma_clip!(x, sigma; fill=:clamp, center=median(x), std=std(x))
sigma_clip!(x, sigma_low, sigma_high; fill=:clamp, center=median(x), std=std(x))

In-place version of sigma_clip

BackgroundMeshes.LocationEstimator

This abstract type embodies the possible background estimation algorithms for dispatch with estimate_background.

To implement a new estimator, you must define the struct and define a method like (::MyEstimator)(data::AbstractArray; dims=:).

See Also

• Location Estimators

MMMBackground(median_factor=3, mean_factor=2)

Estimate the background using a mode estimator of the form median_factor * median - mean_factor * mean. This algorithm is based on the MMMBackground routine originally implemented in DAOPHOT. MMMBackground uses factors of median_factor=3 and mean_factor=2 by default. This estimator assumes that contaminated sky pixel values overwhelmingly display positive departures from the true value.

Examples

julia> x = ones(3, 5);

julia> MMMBackground()(x)
1.0

julia> MMMBackground(median_factor=4, mean_factor=3)(x, dims = 1)
1×5 Matrix{Float64}:
 1.0  1.0  1.0  1.0  1.0

See Also

• SourceExtractorBackground

SourceExtractorBackground()

This estimator returns the background of the input using the SourceExtractorBackground algorithm.

The background is calculated using a mode estimator of the form (2.5 * median) - (1.5 * mean).

If (mean - median) / std > 0.3 then the median is used and if std = 0 then the mean is used.

Examples

julia> data = ones(3, 5);

julia> SourceExtractorBackground()(data)
1.0

julia> SourceExtractorBackground()(data, dims=1)
1×5 Matrix{Float64}:
 1.0  1.0  1.0  1.0  1.0

BiweightLocationBackground(c = 6.0, M = nothing)

Estimate the background using the robust biweight location statistic.

See BiweightStats.jl for more information.

Examples

julia> x = ones(3,5);

julia> BiweightLocationBackground()(x)
1.0

julia> BiweightLocationBackground(c=5.5)(x; dims = 1)
1×5 Matrix{Float64}:
 1.0  1.0  1.0  1.0  1.0

BackgroundMeshes.RMSEstimator

This abstract type embodies the possible background RMS estimation algorithms for dispatch with estimate_background.

To implement a new estimator, you must define the struct and define a method like (::MyRMSEstimator)(data::AbstractArray; dims=:).

See Also

• RMS Estimators

StdRMS()

Uses the standard deviation statistic for background RMS estimation.

Examples

julia> data = ones(3, 5);

julia> StdRMS()(data)
0.0

julia> StdRMS()(data, dims=1)
1×5 Matrix{Float64}:
 0.0  0.0  0.0  0.0  0.0

MADStdRMS()

Uses the standard median absolute deviation (MAD) statistic for background RMS estimation.

This is typically given as

$\sigma \approx 1.4826 \cdot \text{MAD}$

Examples

julia> data = ones(3, 5);

julia> MADStdRMS()(data)
0.0

julia> MADStdRMS()(data, dims=1)
1×5 Matrix{Float64}:
 0.0  0.0  0.0  0.0  0.0

BiweightScaleRMS(c=9.0, M=nothing)

Uses the robust biweight scale statistic for background RMS estimation.

The biweight scale is the square root of the biweight midvariance. The biweight midvariance uses a tuning constant, c, and an optional initial guess of the central value M.

See BiweightStats.jl for more information.

Examples

julia> data = ones(3, 5);

julia> BiweightScaleRMS()(data)
0.0

julia> BiweightScaleRMS(c=3.0)(data, dims=1)
1×5 Matrix{Float64}:
 0.0  0.0  0.0  0.0  0.0

BackgroundInterpolator

This abstract type embodies the different ways of converting a low-resolution mesh into a high-resolution image, especially for dispatch with estimate_background

To implement a new interpolation scheme, you must define the struct and define a method like (::MyInterpolator)(mesh)

See Also

• Interpolators

ZoomInterpolator(factors)

Use a cubic-spline interpolation scheme to increase resolution of a mesh.

factors represents the level of "zoom", so an input mesh of size (10, 10) with factors (2, 2) will have an output size of (20, 20). If only an integer is provided, it will be used as the factor for every axis.

Examples

julia> ZoomInterpolator(2)([1 0; 0 1])
4×4 Matrix{Float64}:
  1.0          0.75   0.25   -2.77556e-17
  0.75         0.625  0.375   0.25
  0.25         0.375  0.625   0.75
 -5.55112e-17  0.25   0.75    1.0

julia> ZoomInterpolator(3, 1)([1 0; 0 1])
6×2 Matrix{Float64}:
  1.0          -2.77556e-17
  1.0          -2.77556e-17
  0.666667      0.333333
  0.333333      0.666667
 -5.55112e-17   1.0
 -5.55112e-17   1.0

IDWInterpolator(factors; leafsize=10, k=8, power=1, reg=0, conf_dist=1e-12)

Use Shepard Inverse Distance Weighing interpolation scheme to increase resolution of a mesh.

factors represents the level of "zoom", so an input mesh of size (10, 10) with factors (2, 2) will have an output size of (20, 20). If only an integer is provided, it will be used as the factor for every axis.

The interpolator can be called with some additional parameters:

• leaf_size determines at what number of points to stop splitting the tree further,
• k which is the number of nearest neighbors to be considered,
• power is the exponent for distance in the weighing factor,
• reg is the offset for the weighing factor in denominator,
• conf_dist is the distance below which two points would be considered as the same point.

Examples

julia> IDWInterpolator(2, k=2)([1 0; 0 1])
4×4 Matrix{Float64}:
 1.0   0.75      0.25      0.0
 0.75  0.690983  0.309017  0.25
 0.25  0.309017  0.690983  0.75
 0.0   0.25      0.75      1.0

julia> IDWInterpolator(3, 1; k=2, power=4)([1 0; 0 1])
6×2 Matrix{Float64}:
 1.0        0.0
 1.0        0.0
 0.941176   0.0588235
 0.0588235  0.941176
 0.0        1.0
 0.0        1.0