ImageStacking.jl

NORMAL_STD_SQRTBWMV_RATIO

The ratio betwen the standard deviation and the square root of the biweight midvariance of a standard normal distribution.

AbstractSigmaClipping{T} <: StackingMethod

Supertype for methods based on sigma clipping, which iteratively reject outliers lying a given number of standard deviations from the median until none are rejected.

GeneralizedESD{T<:Real} <: StackingMethod

Performs the [generalized extreme Studentized deviate test (GESDT)][Rosner1983] to reject outliers.

[Rosner1983]: https://doi.org/10.1080/00401706.1983.10487848

IKSSEstimator{T} <: NormalizationEstimator{T}

Iterative k-sigma estimator of location and scale.

ImageSequence{M}(f, images)

Lazily produces images of type M. images may be an iterable collection of any data type I (e.g. String for filenames) so long as f(images) returns a result of type M.

MADClipping{T<:Real} <: AbstractSigmaClipping{T<:Real}

Modified sigma clipping based on the median and median absolute deviation (MAD) of a dataset.

MeanStacking <: StackingMethod

Produces the mean without any outlier rejection. This method is not recommended for real astronomical data, since outliers are common enough to seriously affect the final result.

MedianMADEstimator{T} <: NormalizationEstimator{T}

Calculates location with the median and scale with the median absolute deviation (MAD).

MedianStacking <: StackingMethod

Produces the median, which is essentially a fully clipped mean. This method is not recommended for stacking any more than a few frames, since the median cannot significantly increase the precision of the data. This leads to posterization, especially in darker areas of astronomical images.

NormalizationCoefficients{T<:Real} <: AbstractVector{Tuple{T,T}}

Stores the location and dispersion data for normalization of images in a stack. Additionally, this type includes a choice of reference location and dispersion that are subtracted and divided, respectively.

NormalizationCoefficients(f, locations::AbstractVector, [dispersions::AbstractVector])
NormalizationCoefficients(
    index::Integer,
    locations::AbstractVector,
    [dispersions::AbstractVector]
)

Converts locations and dispersions into a Tuple making up a NormalizationCoefficents object, and acquires the reference location and dispersion by applying a function f to both input vectors, or using an integer index.

If dispersions is not specified, it defaults to ones(eltype(locations), length(locations)) so that no scaling normalization is performed.

NormalizationEstimator{T}

Represents a method of calculating the location and dispersion of an image, with both results represented as type T. To apply a normalization estimator, call an instance of it as a function.

PixelStats{T}

Represents statistical information for a pixel in a stack:

• The scale of the data (usually the mean)
• The dispersion of the data (usually the standard deviation, but it is the median absolute deviation for R<:MedianRejection)
• The number of pixels in the sample
• The number of pixels rejected for being too low and too high

SigmaClipping{T<:Real} <: AbstractSigmaClipping{T<:Real}

Ordinary sigma clipping based on the median and standard deviation of a dataset.

StackBlock{T<:Number} <: AbstractVector{Matrix{T<:Number}}

Contains all of the data needed to perform stacking.

StackBlock can only store numerical data. Color data should be broken down into individual data channels before stacking.

StackBlock{T}(f, images, region::NTuple{2,R})

Generates a StackBlock from a collection of images.

The function f is used to transform the elements of images into data that can be stored in an AbstractMatrix

StackingMethod

Supertype for all methods used to stack images.

Subtypes of StackingMethod should include all parameters needed to perform the operation, such as rejection thresholds, that do not depend on the images being stacked.

TrimmedMeanStacking{T} <: StackingMethod

TrimmedMeanStacking{T}(lo::Real, hi::Real)
TrimmedMeanStacking{T}(lohi::Real)
TrimmedMeanStacking(lo::Real, hi::Real)
TrimmedMeanStacking(lohi::Real)

Produces a trimmed mean, rejecting the lowest and highest quantiles of the data as specified. This will always reject outliers, but it may also reject good data, so more selective rejection methods are generally recommended.

The standard error of the trimmed mean is calculated from the Winsorized standard deviation (stdw) with the same rejection fractions, and the number of samples (n) [1]:

stdw / ((1 - (lo + hi)) * sqrt(n))

[1]: https://www.itl.nist.gov/div898/software/dataplot/refman2/auxillar/trimmse.htm

WinsorizedSigmaClipping{T<:Real} <: AbstractSigmaClipping{T<:Real}

Winsorized sigma clipping, a modified version of sigma clipping which first performs winsorization on the data before sigma clipping. This procedure is iterated until no samples are rejected.

accepted(p::PixelStats) -> Int

Returns the number of pixels accepted in the stack. This is equal to p.count - sum(rejections(p)).

apply_normalization!(
    op::Union{typeof(+),typeof(*)},
    pixel!::AbstractVector,
    coeffs::ImageStacking.NormalizationCoefficents
)

Applies normalization to a set of pixel values. This may be additive or multiplicative, depending on whether op is + or *.

bwmv(itr)

Compute the biweight midvariance of the collection itr.

bwmvm(itr, m)

Compute the biweight midvariance (BWMV) of the collection itr given a known median m.

bwmvmsorted(itr, m)

Compute the biweight midvariance (BWMV) of a sorted collection itr more efficiently.

create_blocks(
    T,
    image_size,
    image_count,
    [memory_fraction = 0.5],
    [nthreads = Threads.nthreads(:default),]
    [free_memory = Sys.free_memory]
) -> Vector{StackBlock{T}}

Creates a vector of uninitialized StackBlock objects that can hold the desired number of images of the given size and data type. The number of blocks depends on the number of threads desired, which can be determined automatically or manually specified. The memory_fraction parameter determines how much of the available memory

ImageStacking.eachframe(sb::StackBlock)

Creates slices of each image in a StackBlock.

ImageStacking.eachpixel(sb::StackBlock)

Creates slices of each pixel in a StackBlock. Operations that calculate pixel statistics should use this iterator.

get_normalization(f, e::NormalizationEstimator{T}, images) -> NormalizationCoefficents{T}
get_normalization(i::Integer, e::NormalizationEstimator{T}, images)

Calculates normalization coefficients for a sequence of images. The normalizations may be provided with reference to a central estimate of the location and dispersion parameters through a function f, or to the index i of a reference image.

Because normalization can take a long time for each image depending on the method used, this function is multithreaded and will use all available threads to compute the normalization of a sequence.

ikss!(A, k = 4, tol = eps(Float32)) -> Tuple{Real, Real, Int, Int}

Performs iterative k-sigma estimation of location and scale (IKSS) on an array A, which is modified in-place. This estimator is used for image normalization and scaling.

The parameters of the output are:

• location
• scale
• count of pixels not rejected
• number of iterations performed

ikss(itr, k = 4, tol = eps(Float32)) -> Tuple{Real, Real, Int, Int}

Performs iterative k-sigma estimation of location and scale (IKSS). This estimator is used for image normalization and scaling.

The parameters of the output are:

• location
• scale
• count of pixels not rejected
• number of iterations performed

mad(itr)

Compute the median absolute deviation (MAD) of a collection itr.

madm(itr, m)

Compute the median absolute deviation (MAD) of a collection itr, with the known median m.

ImageStacking.pixel_stack!(A!::AbstractVector, s::StackingMethod) -> PixelStats{T}

Stacks the pixel data A! using the stacking method s, potentially modifying A! in place. This returns a PixelStats object, containing the scale and dispersion of the data, along with the number of sampled and rejected pixels. Note that this function may not modify A! depending on the method used (such as calculating a mean without rejection).

This function should only be called if it is both possible and acceptable to modify the input. Otherwise, use pixel_stack.

pixel_stack!(
    A!::AbstractVector,
    s::StackingMethod,
    coeffs::NormalizationCoefficients,
    op::Union{typeof(+),typeof(*)}
) -> PixelStats{T}

Performs pixel stacking with normalization, given a set of normalization coefficients and either the + or * operator depending on whether additive or multiplicative normalization is desired.

pixel_stack([::Type{T}], itr, s::StackingMethod) -> PixelStats{R,T}

Stacks pixel data in an iterator itr with stacking method s. This returns a PixelStats object, containing the scale and dispersion of the data, along with the number of sampled and rejected pixels.

If it is both possible and non-disruptive to modify the pixel data in place, it may be preferable to call [ImageStacking.pixel_stack!] instead, which does not allocate a new array.

rejections(p::PixelStats) -> Tuple{Int,Int}

Returns the number of pixels rejected for falling below or above the rejection thresholds.

ImageStacking.sigma_clip!(A!::AbstractVector, s_lo, s_hi; by = std, sorted::Bool = false)
    -> Tuple{Int, Int}

Performs sigma clipping on A! after sorting it in place, returning the number of pixels rejected for lying below and above the thresholds relative to the median. By default, the standard deviation is used, but this can be changed to a more robust measure of statistical dispersion by changing the by parameter to a different function. Ideally, the function used to calculate the dispersion at each iteration should be able to take advantage of the sorting of the data (e.g. ImageStacking.madsorted is a better choice than ImageStacking.mad for calculating the median absolute deviation).

ImageStacking.stack!(
    output::AbstractMatrix,
    block::ImageStacking.StackBlock,
    s::RejectionMethod,
    [coeffs::NormalizationCoefficients,]
    [op::Union{typeof(+),typeof(*)}]
)

Stacks the data in block and writes the results to output. The region indices of block must be contained within output; it will not be resized to accomodate data which may be out of bounds. Data in block may be modified depending on the choice of rejection method.

If normalization coefficients and a choice of normalization method (either + for additive or * for multiplicative) are provided, then normalization will be applied to the images before they are stacked.

std_err_mean(p::PixelStats)

Estimates the standard error in the mean from the standard deviation and number of accepted pixels in the stack.

target_axes(sb::StackBlock)

Returns the region of the output image that stacking of this block will write to.

trimmed_mean_weights(T::Type, sz::Integer, lo::Real, hi::Real)

Calculates weights needed for the trimmed mean with trimming fractions lo and hi, handling cases where the size of the dataset sz multiplied by either lo or hi is not an integer.

ImageStacking.winsorize_for_sigma_clip!(
    A!::AbstractVector;
    tol = 0.0005,
    s_low = 1.5,
    s_high = 1.5,
    sorted = false
)

Performs iterative Winsorization of the input data with respect to its median and standard deviation, sorting and modifying it in-place.