Center angular value x to be within a symmetric range of length period around at, from at - period/2 to at + period/2. Assumes circular structure: x + period is equivalent to x.

julia> Circular.center_angle(0)
0.0

julia> Circular.center_angle(4π + 1)
1.0

julia> Circular.center_angle(4π - 1)
-1.0

julia> Circular.center_angle(10, at=0, period=3)
1.0

Distance between two angles, x and y. Assumes circular structure: x + period is equivalent to x.

julia> Circular.distance(0, 1)
1.0

julia> Circular.distance(0, 4π + 1)
1.0

julia> Circular.distance(0, 5.5, period=3)
0.5

Median absolute deviation (MAD) of a collection of circular data.

julia> Circular.mad([0])
0.0

julia> Circular.mad([0, 1, 2])
1.0

julia> Circular.mad([0, 2π + 1, 2])
1.0

julia> Circular.mad([0, 1, 2], -2..4) ≈ 1
true

Mean of a collection of circular data.

julia> Circular.mean([0, 1, 2, 3])
1.5

julia> Circular.mean([1, 2π]) ≈ 0.5
true

julia> Circular.mean([1, 5], 0..4) ≈ 1
true

Median of a collection of circular data.

Computes the median that minimizes the sum of arc distances sense. Always returns one of the datapoints, so the result is a medoid.

For discussion of different circular medians see e.g. https://hci.iwr.uni-heidelberg.de/sites/default/files/profiles/mstorath/files/storath2017fast.pdf.

julia> Circular.median([0, 1, 2])
1

julia> Circular.median([0.05, 2π - 0.1, 6π + 0.1])
0.05

julia> Circular.median([0, 1, 2], -2..4)
1.0

Sample range - the shortest arc distance encompassing all of the data in the collection.

julia> Circular.sample_range([-1, 0, 2])
3.0

julia> Circular.sample_range([-1, 0, 1, 2, 3, 4])
5.0

julia> Circular.sample_range([-1, 0, 2, 3, 4])
4.283185307179586

julia> Circular.sample_range([-1, 0, 2, 5, 6])
3.2831853071795862

julia> Circular.sample_range([-1, 4π])
1.0

julia> Circular.sample_range([0, 1], 0..π)
1.0

Standard deviation of a collection of circular data.

julia> Circular.std([0])
0.0

julia> Circular.std([0, 1, 2, 3])
1.2216470118898806

julia> Circular.std([0, 2π])
0.0

julia> Circular.std([0, 1, 2, 3], -10..10)
1.126024231452878

Transform x to be within the range rng assuming circular structure: x + width(rng) is equivalent to x. In effect, this adds the necessary multiple of width(rng) to x so that it falls into rng.

This is deprecated, and means the same as mod(x, rng).

julia> Circular.to_range(0, 0..2π)
0.0

julia> Circular.to_range(4π + 1, 0..2π)
1.0

julia> Circular.to_range(5.5, -1..1)
-0.5

unwrap!(A; refix=firstindex(A), period=2π, tol=period/2)

Assumes A is a sequence of values that has been wrapped with the given period, and undoes the wrapping by identifying discontinuities. Whenever the jump between consecutive values is greater than or equal to tol, shift the later value by adding the proper multiple of period.

unwrap(A; refix=firstindex(A), period=2π, tol=period/2)

Assumes A is a sequence of values that has been wrapped with the given period, and undoes the wrapping by identifying discontinuities. Whenever the jump between consecutive values is greater than or equal to tol, shift the later value by adding the proper multiple of period.

Variance of a collection of circular data.

wrap_curve_closed([f=identity], data; rng)

Assuming data represents a closed curve with circular structure in f.(data), wrap data so that it goes from minimum(rng) + eps to maximum(rng) - eps. A common usecase is plotting such curves.

julia> wrap_curve_closed(identity, [-20., 0, 100, 200]; rng=-180..180)
[-180, -160, -20, 0, 100, 180]  # approximately: endpoints are slightly moved inwards

Geometric Median absolute deviation (MAD) of a collection of points.

Follows the same definition as the univariate MAD, with geometric median instead of the regular median. Rotation invariant, unlike [https://en.wikipedia.org/wiki/Medianabsolutedeviation#Geometricmedianabsolute_deviation].

Geometric median of a collection of points. Points can be specified as real numbers (1d), complex numbers (2d), or arbitrary vectors.

See [https://en.wikipedia.org/wiki/Geometric_median].

julia> geometric_median([1, 2, 3])
2.0

julia> geometric_median([0, 1, 1im, 1+1im]) ≈ 0.5+0.5im
true

julia> geometric_median([[0, 0], [0, 1], [1, 0], [1, 1]]) ≈ [0.5, 0.5]
true

Select a pair of most distant points in the collection. Points can be specified as real numbers (1d), complex numbers (2d), or arbitrary vectors.

julia> most_distant_points([1, 2, 3])
(3, 1)

julia> most_distant_points([0, 1, 1+1im])
(1 + 1im, 0 + 0im)

julia> most_distant_points([[0, 0], [0, 1], [1, 1]])
([1, 1], [0, 0])

Select indices of a pair of most distant points in the collection. Points can be specified as real numbers (1d), complex numbers (2d), or arbitrary vectors.

julia> most_distant_points_ix([1, 2, 3])
(3, 1)

julia> most_distant_points_ix([0, 1, 1+1im])
(3, 1)

julia> most_distant_points_ix([[0, 0], [0, 1], [1, 1]])
(3, 1)