[12] Circular Data#

pysht.circular accepts angles in arbitrary units through period; values are reduced modulo that period. The default is \(2\pi\) radians.

Scientific question

Function

Calibration

Is the first trigonometric moment nonzero?

rayleigh

Monte Carlo circular-uniform null

Is there any departure detectable by Watson \(U^2\)?

watson

Monte Carlo circular-uniform null

Is there an omnibus, possibly multimodal departure?

hermans_rasson

Monte Carlo circular-uniform null

Are two or more continuous circular distributions equal?

mardia_watson_wheeler_ksamp

exact or Monte Carlo label permutation

Rayleigh is deliberately described as a targeted first-harmonic test: a distribution can be nonuniform while its first trigonometric moment is zero. Watson and modified Hermans–Rasson are omnibus tests. Rayleigh reports the mean resultant length and, when it is numerically defined, the mean direction in the same units as the input.

All one-sample routines use corrected Monte Carlo p-values and default to 9,999 draws. The Mardia–Watson–Wheeler routine conditions on the pooled directions. Automatic calibration="permutation" is exact when the complete ordered allocation orbit fits the resampling budget. Because this API follows the continuous-rank statistic, pooled ties are rejected rather than silently receiving an undocumented grouped-data correction.

See the method ledgers for Rayleigh, Watson, modified Hermans–Rasson, and Mardia–Watson–Wheeler.

Functions#

Tests for circular uniformity and equality of circular distributions.

Angles are accepted in arbitrary units through the explicit period parameter and are reduced modulo that period before calculation. The one-sample procedures use finite-sample Monte Carlo calibration under the continuous circular-uniform null. The multi-sample procedure conditions on the pooled directions and permutes group labels.

pysht.circular.hermans_rasson(x, *, period=_TAU, calibration='monte-carlo', n_resamples=9_999, rng=None)[source]#

Perform the modified Hermans–Rasson omnibus test (1985).

The pairwise Sobolev kernel uses the paper’s recommended coefficient 2.895. This version is sensitive to both unimodal and multimodal departures and rejects for large statistic values.

Parameters:

  • x (ArrayLike)

  • period (float)

  • calibration (str)

  • n_resamples (int)

  • rng (int | integer | Generator | None)

Return type:

ResamplingTestResult

pysht.circular.mardia_watson_wheeler_ksamp(*samples, period=_TAU, calibration='permutation', n_resamples=9_999, rng=None)[source]#

Test equality of two or more continuous circular distributions.

Pooled circular ranks are converted to uniform trigonometric scores and group labels are permuted with their original sizes fixed. Exact mode enumerates every ordered allocation. Tied directions are rejected because the continuous-rank statistic has no uniquely specified grouped-data correction in this API.

Parameters:

  • samples (ArrayLike)

  • period (float)

  • calibration (str)

  • n_resamples (int)

  • rng (int | integer | Generator | None)

Return type:

ResamplingTestResult

pysht.circular.rayleigh(x, *, period=_TAU, calibration='monte-carlo', n_resamples=9_999, rng=None)[source]#

Perform Rayleigh’s test against first-harmonic circular alternatives.

This is a targeted test for a nonzero first trigonometric moment, not an omnibus test of circular uniformity. Large values of n Rbar**2 are significant. Monte Carlo calibration is exact up to simulation error for every sample size under the continuous circular-uniform null.

Parameters:

  • x (ArrayLike)

  • period (float)

  • calibration (str)

  • n_resamples (int)

  • rng (int | integer | Generator | None)

Return type:

ResamplingTestResult

pysht.circular.watson(x, *, period=_TAU, calibration='monte-carlo', n_resamples=9_999, rng=None)[source]#

Perform Watson’s rotation-invariant U^2 uniformity test (1961).

Parameters:

  • x (ArrayLike)

  • period (float)

  • calibration (str)

  • n_resamples (int)

  • rng (int | integer | Generator | None)

Return type:

ResamplingTestResult