Autocorrelation function (ACF) computation and related statistics.
Provides FFT-based ACF computation for detecting sample non-independence in benchmark results, along with derived statistics for quantifying the impact on statistical reliability.
Main functions:
acf - Compute autocorrelation coefficients for all lagsljung-box - Ljung-Box Q statistic and p-value for independence testingeffective-sample-size - Adjusted sample size accounting for autocorrelationci-inflation-factor - Factor to widen confidence intervalsAutocorrelation function (ACF) computation and related statistics. Provides FFT-based ACF computation for detecting sample non-independence in benchmark results, along with derived statistics for quantifying the impact on statistical reliability. Main functions: - `acf` - Compute autocorrelation coefficients for all lags - `ljung-box` - Ljung-Box Q statistic and p-value for independence testing - `effective-sample-size` - Adjusted sample size accounting for autocorrelation - `ci-inflation-factor` - Factor to widen confidence intervals
(acf samples)Compute autocorrelation function using FFT.
Algorithm:
Returns map with ACF values for lags 1 to floor(n/2): {1 r1, 2 r2, ...}
Edge cases:
Compute autocorrelation function using FFT.
Algorithm:
1. Center samples (subtract mean)
2. Zero-pad to 2*next-power-of-2(n) for circular -> linear correlation
3. FFT, compute power spectrum (multiply by conjugate)
4. IFFT to get autocorrelation
5. Normalize by r₀ (variance * n)
Returns map with ACF values for lags 1 to floor(n/2): {1 r1, 2 r2, ...}
Edge cases:
- n < 20: logs warning, returns nil
- Zero variance: logs warning, returns nil(analyse-autocorrelation samples)Compute autocorrelation function and lag severity from samples.
Returns map with: :acf - map of lag -> autocorrelation coefficient :lag-1 - {:value r₁ :severity <keyword>} :lag-severities - map of lag -> severity for all lags :anomalous-lags - vector of lag numbers with non-trivial severity :effective-sample-size - {:n-original n} (for downstream analyses)
Use effective-sample-size-analysis and autocorrelation-classification separately to compute ESS and pattern/classification results.
Returns nil if samples are insufficient (n < 20) or have zero variance.
Compute autocorrelation function and lag severity from samples.
Returns map with:
:acf - map of lag -> autocorrelation coefficient
:lag-1 - {:value r₁ :severity <keyword>}
:lag-severities - map of lag -> severity for all lags
:anomalous-lags - vector of lag numbers with non-trivial severity
:effective-sample-size - {:n-original n} (for downstream analyses)
Use effective-sample-size-analysis and autocorrelation-classification
separately to compute ESS and pattern/classification results.
Returns nil if samples are insufficient (n < 20) or have zero variance.(anomalous-lags lag-severities)Extract lags with non-trivial severity from a lag-severities map.
Returns vector of lag numbers where severity is not :none or :alternating-none, sorted ascending. Severity can be looked up in the lag-severities map.
Extract lags with non-trivial severity from a lag-severities map. Returns vector of lag numbers where severity is not :none or :alternating-none, sorted ascending. Severity can be looked up in the lag-severities map.
(autocorrelation-classification acf-map n)Compute pattern detection and classification from ACF results.
Takes ACF results (the :acf map) and original sample count.
Returns map with: :ljung-box - {:q-statistic Q :df h :p-value p} :pattern - :clean, :transient-effects, :drift, :periodic, :severe, or :alternating-* :classification - :pass, :acceptable, :warning, or :fail :detected-period - Integer period for :periodic pattern, nil otherwise :noise-floor - 2/√n threshold value :thresholds - {:lag-1 {:minor 0.10 :moderate 0.20 :severe 0.35} :other {:minor 0.15 :moderate 0.25 :severe 0.40}}
Returns nil if acf-map is nil.
Compute pattern detection and classification from ACF results.
Takes ACF results (the :acf map) and original sample count.
Returns map with:
:ljung-box - {:q-statistic Q :df h :p-value p}
:pattern - :clean, :transient-effects, :drift, :periodic, :severe, or :alternating-*
:classification - :pass, :acceptable, :warning, or :fail
:detected-period - Integer period for :periodic pattern, nil otherwise
:noise-floor - 2/√n threshold value
:thresholds - {:lag-1 {:minor 0.10 :moderate 0.20 :severe 0.35}
:other {:minor 0.15 :moderate 0.25 :severe 0.40}}
Returns nil if acf-map is nil.(ci-inflation-factor r1)Compute confidence interval inflation factor due to autocorrelation.
CI_inflation = sqrt((1 + r1) / (1 - r1))
Minimum value is 1.0. Capped at 6.0 if r1 >= 0.95.
Parameters: r1 - lag-1 autocorrelation coefficient
Returns the inflation factor as a double.
Compute confidence interval inflation factor due to autocorrelation. CI_inflation = sqrt((1 + r1) / (1 - r1)) Minimum value is 1.0. Capped at 6.0 if r1 >= 0.95. Parameters: r1 - lag-1 autocorrelation coefficient Returns the inflation factor as a double.
(classify-lag-severities acf-map n)Classify severity for all lags in an ACF map.
Returns map of lag -> severity keyword.
Classify severity for all lags in an ACF map. Returns map of lag -> severity keyword.
(classify-overall lag-severities ljung-box-result n-eff n)Classify overall autocorrelation assessment.
Classification:
Alternating severities (negative autocorrelation) are treated more leniently since they don't reduce effective sample size.
Parameters: lag-severities - map of lag -> severity from classify-lag-severities ljung-box-result - result from ljung-box function n-eff - effective sample size n - original sample size
Returns classification keyword.
Classify overall autocorrelation assessment. Classification: - :pass - all lags at :none AND Ljung-Box p > 0.10 - :acceptable - lag-1 at :none or :minor AND no lag at :severe - :warning - any lag at :moderate OR Ljung-Box p ≤ 0.01 - :fail - any lag at :severe OR n_eff < n/3 Alternating severities (negative autocorrelation) are treated more leniently since they don't reduce effective sample size. Parameters: lag-severities - map of lag -> severity from classify-lag-severities ljung-box-result - result from ljung-box function n-eff - effective sample size n - original sample size Returns classification keyword.
(detect-pattern acf-map n)Detect autocorrelation pattern from ACF values.
Patterns:
Returns pattern keyword.
Detect autocorrelation pattern from ACF values. Patterns: - :clean - all lags below 2/√n threshold - :alternating-none - negative r₁ below noise floor - :alternating-minor - negative r₁ at minor severity - :alternating-moderate - negative r₁ at moderate severity - :alternating-severe - negative r₁ at severe severity - :severe - lag-1 at severe level - :drift - slow decay; lag-⌊n/10⌋ still above threshold - :transient-effects - lag-1 elevated with decaying correlation (r₁ > r₂ > r₃) - :periodic - lag-1 clean but peak at k > 5 exceeds threshold Returns pattern keyword.
(detect-period acf-map n)Detect periodic pattern by finding peak lag > 5 with max |rₖ|.
Returns the lag of the peak if it exceeds threshold, nil otherwise.
Detect periodic pattern by finding peak lag > 5 with max |rₖ|. Returns the lag of the peak if it exceeds threshold, nil otherwise.
(effective-sample-size r1 n)Compute effective sample size accounting for lag-1 autocorrelation.
n_eff = n * (1 - r1) / (1 + r1)
Clamped to [1, n]. If r1 <= 0, returns n (negative autocorrelation doesn't reduce effective sample size in the same way).
Parameters: r1 - lag-1 autocorrelation coefficient n - original sample size
Returns effective sample size as a long.
Compute effective sample size accounting for lag-1 autocorrelation. n_eff = n * (1 - r1) / (1 + r1) Clamped to [1, n]. If r1 <= 0, returns n (negative autocorrelation doesn't reduce effective sample size in the same way). Parameters: r1 - lag-1 autocorrelation coefficient n - original sample size Returns effective sample size as a long.
(effective-sample-size-analysis acf-map n)Compute effective sample size and CI inflation factor from ACF results.
Takes ACF results (the :acf map) and original sample count.
Returns map with: :effective-sample-size - {:n-original n :n-effective n_eff :ratio ratio} :ci-inflation-factor - inflation factor for CIs
Returns nil if acf-map is nil.
Compute effective sample size and CI inflation factor from ACF results.
Takes ACF results (the :acf map) and original sample count.
Returns map with:
:effective-sample-size - {:n-original n :n-effective n_eff :ratio ratio}
:ci-inflation-factor - inflation factor for CIs
Returns nil if acf-map is nil.(lag-1-severity r1 n)Classify lag-1 autocorrelation severity.
For positive autocorrelation (consecutive samples correlated):
For negative autocorrelation (alternating pattern), uses :alternating-* variants. Negative autocorrelation doesn't reduce effective sample size the same way positive does, so these are informational rather than warnings.
Returns keyword :none, :minor, :moderate, :severe, or :alternating-* variant.
Classify lag-1 autocorrelation severity. For positive autocorrelation (consecutive samples correlated): - :none - |r₁| < max(0.10, 2/√n) - :minor - 0.10 ≤ |r₁| < 0.20 - :moderate - 0.20 ≤ |r₁| < 0.35 - :severe - |r₁| ≥ 0.35 For negative autocorrelation (alternating pattern), uses :alternating-* variants. Negative autocorrelation doesn't reduce effective sample size the same way positive does, so these are informational rather than warnings. Returns keyword :none, :minor, :moderate, :severe, or :alternating-* variant.
(lag-severity rk n)Classify severity for lags other than lag-1.
Thresholds (above noise floor 2/√n):
Returns keyword :none, :minor, :moderate, or :severe.
Classify severity for lags other than lag-1. Thresholds (above noise floor 2/√n): - :none - |rₖ| < max(0.15, 2/√n) - :minor - 0.15 ≤ |rₖ| < 0.25 - :moderate - 0.25 ≤ |rₖ| < 0.40 - :severe - |rₖ| ≥ 0.40 Returns keyword :none, :minor, :moderate, or :severe.
(ljung-box acf-map n)Compute Ljung-Box Q statistic for testing autocorrelation.
Q = n(n+2) * sum_k=1^h (rk^2/(n-k))
where h = min(20, floor(n/4))
Returns map with: :q-statistic - the Q value :df - degrees of freedom (h) :p-value - 1 - chi-squared-cdf(Q, h)
Returns nil if acf-map is nil.
Parameters:
acf-map - map of lag -> autocorrelation from acf function
n - original sample size
Compute Ljung-Box Q statistic for testing autocorrelation. Q = n(n+2) * sum_k=1^h (rk^2/(n-k)) where h = min(20, floor(n/4)) Returns map with: :q-statistic - the Q value :df - degrees of freedom (h) :p-value - 1 - chi-squared-cdf(Q, h) Returns nil if acf-map is nil. Parameters: acf-map - map of lag -> autocorrelation from `acf` function n - original sample size
(noise-floor n)Compute the noise floor threshold for ACF significance. For a sample of size n, values below 2/√n are indistinguishable from noise.
Compute the noise floor threshold for ACF significance. For a sample of size n, values below 2/√n are indistinguishable from noise.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |