API Reference

Curve{T} <: AbstractCurve

Datatype holding x-y data. x and y vectors have to have the same length.

Fields

• x :: Vector{T} : x-grid
• y :: Vector{T} : y-values

Constructors

Curve(x, y)
Curve(y)

Note

Both x and y must be convertabile to vectors with the same element type.

Examples

julia> Curve([2.0, 3.0], [4.0, 5.0])
Curve{Float64}, 2 datapoints
(2.0, 4.0)
(3.0, 5.0)


julia> Curve([2.0, 3.0], [5.0])
ERROR: ArgumentError: x and y need to have the same length.
[...]


julia> Curve([4, 5, 6])
Curve{Int64}, 3 datapoints
(1, 4)
(2, 5)
(3, 6)


julia> Curve(1:3, [1., 2., 3.])
Curve{Float64}, 3 datapoints
(1.0, 1.0)
(2.0, 2.0)
(3.0, 3.0)

NoiseSample <: AbstractCurve

Curve holding a noise sample. At minimum, a constant offset is removed from the noise sample upon construction. If provided, a polynomial of order n is subtracted.

Fields

• x::Vector{Float64} : x-grid
• y::Vector{Float64} : y-value

Constructors

NoiseSample(x::Vector{T}, y::Vector{T})
NoiseSample(x::Vector{T}, y::Vector{T}, n::Int)
NoiseSample(s::Curve)
NoiseSample(s::Curve, n::Int)

Notes

Noise samples should not have a slow trend on top of the noise, otherwise noise parameters cannot be reliably infered. Construct NoiseSample objects with a high enough order n so as to remove any slow variations.

UncertainCurve{T} <: AbstractCurve

Datatype holding x-y data where y-data holds a vector of particles to model uncertainty. x and y vectors have to have the same length.

Fields

• x::Vector{T} : x-grid
• y::Vector{Particles{T, N}} : uncertain y-values

Constructors

UncertainCurve(x::Vector{T}, y::Vector{Particles{N, T}})
UnertainCurve(y::Vector{T})

Examples

julia> using MonteCarloMeasurements


julia> UncertainCurve([2.0, 3.0], [4.0 ± 1.0 , 5.0 ± 1.0])
UncertainCurve{Float64, 2000}, 2 datapoints
(2.0, 4.0 ± 1.0)
(3.0, 5.0 ± 1.0)


julia> UncertainCurve([2.0], [4.0 ± 1.0 , 5.0 ± 1.0])
ERROR: ArgumentError: x and y need to have the same length.
[...]


julia> UncertainCurve([3.0 ± 1.0, 4.0 ± 1.0 , 5.0 ± 1.0])
UncertainCurve{Float64, 2000}, 3 datapoints
(1.0, 3.0 ± 1.0)
(2.0, 4.0 ± 1.0)
(3.0, 5.0 ± 1.0)

GaussianNoiseModel{T <: Real} <: AbstractNoiseModel

Model to describe noise following a univariate Gaussian distribution (uncorrelated noise).

Fields

• σ::T : standard deviation

MvGaussianNoiseModel{T <: Real} <: AbstractNoiseModel

Model to describe noise following a multivariate Gaussian distribution (correlated noise).

Fields

• δx::T: noise grid spacing
• α::T : autocovariance amplitude
• λ::T : autocovaraiance lag

UncertainBound{T, N}

Used to define uncertain integration bounds.

Holds N samples of start and end points of type T for numeric integration.

Fields

• left::Particles{T, N}: samples of starting point
• right::Particles{T, N}: samples of end point

Constructors

UncertainBound(left::S, right::T, N::Int=10_000) where {S <: ContinuousUnivariateDistribution, T <: ContinuousUnivariateDistribution}

Create an UncertainBound from two distributions left and right defining uncertain start and end points of the integration window.

Example

Start point falls in the range [1, 2] with uniform probability, end point falls in the range [5, 6] with uniform probability:

julia> using Distributions

julia> using Random: seed!; seed!(1);

julia> UncertainBound(Uniform(1, 2), Uniform(5, 6), 20_000)
UncertainBound{Float64, 20000}(start = 1.5 ± 0.29, end = 5.5 ± 0.29)

UncertainBound(pos::T, width::ContinuousUnivariateDistribution, uc::UncertainCurve{T, N}) where {T, N}

Create an UncertainBound from a position pos, a distribution for the integration window width width, and an uncertain curve object uc. Useful for integrating symmetric peaks. The constructor will find start and end points for the integration window such that, for each sample in uc, the integration window will be symmetric around the peak that falls in the interval pos ± (sample of width)/2, i.e. the integration window will "follow" the peak position from draw to draw (note that, due to noise, the peak may change its position from draw to draw).

Example

Uncertainty of width is modeled with a scaled and shifted Beta(2, 2) distribution:

julia> uc = begin # create uncertain curve with one symmetric peak
           x = 0:0.1:10;
           y = @. exp(-(x - 5)^2)
           add_noise(Curve(x, y), MvGaussianNoiseModel(0.1, 0.03, 0.5))
       end;

julia> ub = UncertainBound(5., scale_shift_beta(2, 2, 3.5, 4.0), uc)
UncertainBound{Float64, 10000}(start = 3.13 ± 0.064, end = 6.88 ± 0.064)

UncertainBound(pos::Vector{T}, width::ContinuousUnivariateDistribution, uc::UncertainCurve{T, N}) where {T, N}

Create several UncertainBound objects with identical integration window widths in each draw. Useful for integration of several symmetric peaks for which the same width may be assumed.

Example

Uncertainty of width is modeled with a scaled and shifted Beta(2, 2) distribution:

julia> uc = begin # create uncertain curve with one symmetric peak
           x = 0:0.1:10;
           y = @. exp(-(x - 3)^2/0.15) + exp(-(x - 7)^2/0.15)
           add_noise(Curve(x, y), MvGaussianNoiseModel(0.1, 0.03, 0.5))
       end;

julia> ubs = UncertainBound([3., 7.], scale_shift_beta(2, 2, 1.3, 1.5), uc)
2-element Vector{UncertainBound{Float64, 10000}}:
 UncertainBound{Float64, 10000}(start = 2.3 ± 0.022, end = 3.7 ± 0.022)
 UncertainBound{Float64, 10000}(start = 6.3 ± 0.022, end = 7.7 ± 0.022)

crop(s::AbstractCurve, left, right)

Crop a slice from a curve between left and right and return a new curve.

Examples

julia> c = Curve(1:0.5:10, 11:0.5:20)
Curve{Float64}, 19 datapoints
(1.0, 11.0)
(1.5, 11.5)
(2.0, 12.0)
(2.5, 12.5)
(3.0, 13.0)
    ⋮
(8.0, 18.0)
(8.5, 18.5)
(9.0, 19.0)
(9.5, 19.5)
(10.0, 20.0)


julia> crop(c, 2, 3)
Curve{Float64}, 3 datapoints
(2.0, 12.0)
(2.5, 12.5)
(3.0, 13.0)


julia> crop(c, 2.1, 3.5)
Curve{Float64}, 3 datapoints
(2.5, 12.5)
(3.0, 13.0)
(3.5, 13.5)


julia> crop(c, 2.1, 3.9)
Curve{Float64}, 3 datapoints
(2.5, 12.5)
(3.0, 13.0)
(3.5, 13.5)


julia> crop(c, 2.1, 4.0)
Curve{Float64}, 4 datapoints
(2.5, 12.5)
(3.0, 13.0)
(3.5, 13.5)
(4.0, 14.0)

stitch(curves...)

Append curves one after the other.

Useful when cutting out signals from Curves for baseline correction purposes.

add_noise(c::Curve, nm::AbstractNoiseModel, N::Int=10_000)

Add noise from noise model to curve, retrieve UncertainCurve with N samples.

fit_noise(ns::NoiseSample; α_guess=1.0, λ_guess=1.0)

Build a MvGaussianNoiseModel for the NoiseSample ns.

Estimates parameters α and λ by fitting the exponentiated quadratic covariance function

k(Δx) = α² exp(-0.5 (Δx/λ)²)

to the autocovariance (k) vs. the lag (Δx) of the noise sample.

Change initial guess if fit does not converge to sensible result.

plotautocovfit(ns::NoiseSample, nm::MvGaussianNoiseModel; kw...)

Plot results of autocovariance fit.

scale_shift_beta(α, β, a, b)

Create a scaled and shifted Beta(α, β) distribution. Samples fall in the interval [a, b].

mc_integrate(uc::UncertainCurve{T, N}, bnds::Vector{UncertainBound{T, M}}; intfun=trapz)
mc_integrate(uc::UncertainCurve{T, N}, bnds::UncertainBound{T, M}; intfun=trapz)

Integrate uncertain curve using uncertain bound(s).

Applies Monte-Carlo integration algorithm to samples stored in uc and returns one or an array of uncertain areas of type Particles{T, N}.

Keyword arguments

intfun: The core integration function that is used to numerically integrate each draw. Defaults to NoisySignalIntegration.trapz. The function that is used to substitute trapz must share its call signature.

subtract_baseline (deprecated in favor of local_baseline): If true, for each draw a local linear baseline defined by the integration window start and end point will be subtracted.

local_baseline: If true, for each draw a local linear baseline defined by the integration window start and end point will be subtracted. The y-values of the start and end point are derived from a weighted average over the start and end point distributions, see the documentation for further information.

trapz(x::AbstractArray{T}, y::AbstractArray{T}, left, right) where {T<:AbstractFloat}

Integrate vector y in interval [left, right] using trapezoidal integration.

Notes

left and right must support conversion to the datatype T.

If left and right do not fall on the x-grid, additional data points will be interpolated linearly. (i.e. the width of the first and last trapezoid will be somewhat smaller).

If left and/or right falls outside the x-range, the integration window will be cropped to the available range.

Examples

julia> x = collect(Float64, 0:10);

julia> y = ones(Float64, 11);


julia> trapz(x, y, 1, 3)
2.0


julia> trapz(x, y, -1, 11) # at most, we can integrate the available x-range, 0 to 10
10.0


julia> trapz(x, y, -10, 20)
10.0


julia> trapz(x, y, 1.1, 1.3) ≈ 0.2 # if we integrate "between" the grid, data points are interpolated
true

mc_bandcenter(uc::UncertainCurve{T, N}, bnds::Vector{UncertainBound{T, M}})
mc_bandcenter(uc::UncertainCurve{T, N}, bnds::UncertainBound{T, M})

Determines band centers from uncertain curve using uncertain bound(s). Band centers are calculated as the position weighted by intensity (Σᵢxᵢyᵢ)/(Σᵢyᵢ). Much like with the function trapz when integrating, data points are interpolated linearly if the integration bounds happen to fall between the grid spanned by the x-values.

Returns one or an array of band centers of type Particles{T, N}.

Keyword arguments

subtract_baseline (deprecated in favor of local_baseline): If true, for each draw a local linear baseline defined by the integration window start and end point will be subtracted.

local_baseline: If true, for each draw a local linear baseline defined by the integration window start and end point will be subtracted. The y-values of the start and end point are derived from a weighted average over the start and end point distributions, see the documentation for further information.

@samples n::Integer e::Expression

Create a Particles object with n samples using a ± or .. expression.

Examples

julia> using NoisySignalIntegration

julia> @samples 9999 1 ± 1
1.0 ± 1.0 MonteCarloMeasurements.Particles{Float64, 9999}

julia> @samples 9999 1 .. 2
1.5 ± 0.289 MonteCarloMeasurements.Particles{Float64, 9999}

animate_draws(uc::UncertainCurve, bnds::Vector{UncertainBound}; n=20, fps=5, filepath=nothing, kw...)

Create a gif animation showing the first n random draws. Requires the Plots.jl package.

Create an animation of the Monte-Carlo iterations when integrating the UncertainCurve uc using the UncertainBounds bnds.

Keyword arguments

n: number of draws that are included in animation

fps: frames-per-second

filepath: if provided, the gif-animation will be stored using this filepath, otherwise a temporary file will be created.

Further keyword arguments are passed on the Plots.plot() function.