agi.foundation

(agi.foundation.core-2025r1.jar)

Class CircularDescriptiveStatistics

java.lang.Object

agi.foundation.CircularDescriptiveStatistics

public final class CircularDescriptiveStatistics
extends Object

Provides descriptive statistic methods suited for circular data. The algorithms are based on "Directional Statistics" by Mardia and Jupp.

Method Summary

Modifier and Type	Method and Description
static double	dispersionAboutAngle(List<Double> dataList, double angle) Calculates the dispersion of a list of angles about a given angle.
static double	meanDifference(List<Double> dataList) Calculates the mean angular distance between angles in a list.
static double	meanDirection(List<Double> dataList) Calculates the mean direction of a list of angles.
static double	meanResultantLength(List<Double> dataList) Calculates the mean resultant length of a list of angles.
static double	medianDirection(List<Double> dataList) Calculates the median of a list of angles by minimizing E[ π - | π - | θ - φ | | ] where φ is the median angle sought, and θ represents the angles from the input data list.
static double	standardDeviation(List<Double> dataList) Calculates the standard deviation of a list of angles.
static double	variance(List<Double> dataList) Calculates the variance of a list of angles.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

meanDirection

public static double meanDirection(@Nonnull
                                   List<Double> dataList)

Calculates the mean direction of a list of angles.

The output range is (-π, π] and disregards winding. If the mean resultant length is zero, this will return a nonsensical value.

Parameters:

dataList - The list of angles to use to calculate the mean.

Returns:

The mean direction.

Throws:

ArgumentNullException - Thrown when dataList is null.

ArgumentException - Thrown when dataList is empty.

meanResultantLength

public static double meanResultantLength(@Nonnull
                                         List<Double> dataList)

Calculates the mean resultant length of a list of angles.

The output range is 0 ≤ R ≤ 1.

Parameters:

dataList - The list of angles to use to calculate the mean resultant length.

Returns:

The mean resultant length.

Throws:

ArgumentNullException - Thrown when dataList is null.

ArgumentException - Thrown when dataList is empty.

variance

public static double variance(@Nonnull
                              List<Double> dataList)

Calculates the variance of a list of angles.

The output range is 0 ≤ V ≤ 1.

Parameters:

dataList - The list of angles to use to calculate the variance.

Returns:

The circular variance of the angles.

Throws:

ArgumentNullException - Thrown when dataList is null.

ArgumentException - Thrown when dataList is empty.

medianDirection

public static double medianDirection(@Nonnull
                                     List<Double> dataList)

Calculates the median of a list of angles by minimizing E[ π - | π - | θ - φ | | ] where φ is the median angle sought, and θ represents the angles from the input data list.

The output range is (-π, π] and disregards winding.

Parameters:

dataList - The list of angles to use to calculate the median.

Returns:

The circular median of the angles. If the minimizer is unable to find the median then Double.NaN is returned.

Throws:

ArgumentNullException - Thrown when dataList is null.

ArgumentException - Thrown when dataList is empty.

standardDeviation

public static double standardDeviation(@Nonnull
                                       List<Double> dataList)

Calculates the standard deviation of a list of angles.

The output range is [0, ∞]. Returns Double.NaN if the mean resultant length is exactly zero.

Parameters:

dataList - The list of angles to use to calculate the standard deviation.

Returns:

The circular standard deviation of the angles.

Throws:

ArgumentNullException - Thrown when dataList is null.

ArgumentException - Thrown when dataList is empty.

meanDifference

public static double meanDifference(@Nonnull
                                    List<Double> dataList)

Calculates the mean angular distance between angles in a list.

The output range is [0, π/2].

Parameters:

dataList - The list of angles to use to calculate the mean difference.

Returns:

The mean distance between pairs of data points.

Throws:

ArgumentNullException - Thrown when dataList is null.

ArgumentException - Thrown when dataList is empty.

dispersionAboutAngle

public static double dispersionAboutAngle(@Nonnull
                                          List<Double> dataList,
                                          double angle)

Calculates the dispersion of a list of angles about a given angle.

The output range is [0, π]. Winding is ignored.

Parameters:

dataList - The list of angles to use to calculate the dispersion.

angle - The angle around which dispersion is measured.

Returns:

The measure of how the data points are dispersed about the given angle.

Throws:

ArgumentNullException - Thrown when dataList is null.

ArgumentException - Thrown when dataList is empty.