API reference

sigma_clip(x, sigma; kwargs...)
sigma_clip(x, sigma_lower, sigma_upper; kwargs...)

Return a clipped copy of x; integer inputs are converted to floating point. sigma_clip(x, sigma) is shorthand for sigma_clip(x, sigma, sigma). Accepts the same thresholds and keywords as sigma_clip_bounds.

sigma_clip!(x, sigma; kwargs...) -> x
sigma_clip!(x, sigma_lower, sigma_upper; kwargs...) -> x

Replace non-finite values and outliers in x with NaN. The element type must represent NaN. sigma_clip!(x, sigma) is shorthand for sigma_clip!(x, sigma, sigma). Accepts the same thresholds and keywords as sigma_clip_bounds.

sigma_clip_mask(x, sigma; kwargs...) -> BitArray
sigma_clip_mask(x, sigma_lower, sigma_upper; kwargs...) -> BitArray

Return a mask where true marks finite values inside the final clipping bounds. sigma_clip_mask(x, sigma) is shorthand for sigma_clip_mask(x, sigma, sigma). Accepts the same thresholds and keywords as sigma_clip_bounds.

sigma_clip_mask!(x, target, sigma; kwargs...) -> target
sigma_clip_mask!(x, target, sigma_lower, sigma_upper; kwargs...) -> target

Write the validity mask into target, which must have the same axes as x. sigma_clip_mask!(x, target, sigma) is shorthand for sigma_clip_mask!(x, target, sigma, sigma). Accepts the same thresholds and keywords as sigma_clip_bounds.

sigma_clip_bounds(x, sigma; kwargs...) -> (lower, upper)
sigma_clip_bounds(x, sigma_lower, sigma_upper; kwargs...) -> (lower, upper)

Return the final iterative sigma-clipping bounds without modifying x. Non-finite values and entries marked by exclude are ignored while estimating the bounds.

The thresholds are required and must be finite and positive. sigma_clip_bounds(x, sigma) is shorthand for sigma_clip_bounds(x, sigma, sigma). Keywords: workspace=nothing, exclude=nothing, center=fast_median!, spread=mad_std!, and maxiter=5. Use maxiter=-1 to run until convergence.

sigma_clipped_stats(x, sigma; kwargs...) -> NamedTuple
sigma_clipped_stats(x, sigma_lower, sigma_upper; kwargs...) -> NamedTuple

Clip x and calculate statistics on the values retained in the internal workspace buffer. The center and spread callables used for clipping are also returned as the center and spread fields. Additional statistics can be requested with symbol-keyed pairs, for example:

sigma_clipped_stats(
    data, 3;
    :median => fast_median!,
    :madstd => mad_std!,
)

The result is a NamedTuple with center and spread fields followed by the requested pair fields. Each pair callable receives the compacted buffer view as its only argument. The input array is not modified.

The thresholds are required and must be finite and positive. sigma_clipped_stats(x, sigma) is shorthand for sigma_clipped_stats(x, sigma, sigma). Keywords: workspace=nothing, exclude=nothing, center=fast_median!, spread=mad_std!, and maxiter=5. Use maxiter=-1 to run until convergence. Any other keyword is taken as a statistic pair.

fast_median!(a::AbstractVector) -> float(eltype(a))

Compute the median of a in O(n) average time using an in-place quickselect (Wirth's algorithm). Modifies the ordering of a but preserves all values. Returns zero(eltype(a)) for empty input. When used as center=fast_median! in SigmaClip, it reorders only SigmaClip's internal workspace, not the user's input array.

Allocation-free; roughly 2–3× faster than Statistics.median on random data.

See also: mad_std!

mad_std!(a::AbstractVector)

Compute the median absolute deviation of a in place, scaled to match the standard deviation of a normal distribution.

SigmaClipWorkspace(buf::AbstractVector, aux::Union{Nothing, AbstractVector})

Reusable scratch buffers for the workspace keyword of the sigma-clipping functions. buf must have the input's element type and at least as many elements as the input; it receives a copy of the finite, non-excluded values. aux is the scratch buffer needed by mad_std! and must also hold at least as many elements as the input; pass nothing when the spread estimator does not need it.

workspace_buffer(ws) -> AbstractVector

Return the writable main scratch buffer used by SigmaClip. Custom workspace types can implement this method to participate in the workspace API.

workspace_auxbuffer(ws) -> AbstractVector or nothing

Return the auxiliary scratch buffer used by mad_std!, or nothing when it is not available. Custom workspace types can implement this method to participate in the workspace API.