Cluster Statistics

Essential Statistical Functions for Data Analysis and Decision-Making

Basic Descriptive Statistics

stats$max

When to Use: Finding the peak value in a dataset, such as the highest daily stock price in a month.

• Example: A trader analyzes a stock's price history in sample->value1 to identify its maximum value over 100 days.
• Returned Value: The highest value (e.g., 100 for sample->value1).
• Decision: If the stats$max is unusually high (e.g., a stock spike), investigate a market event or sell at the peak.

stats$min

When to Use: Identifying the lowest point, such as the minimum temperature in a weather dataset.

• Example: A farmer checks soil sensor readings in sample->value1 to find the lowest moisture level over a season.
• Returned Value: The smallest value (e.g., 1 for sample->value1).
• Decision: If the stats$min is too low (e.g., drought conditions), increase irrigation or adjust crop planning.

stats$range

When to Use: Measuring the spread between highest and lowest values, such as temperature fluctuation.

• Example: A meteorologist analyzes 100 daily temps in sample->value1.
• Returned Value: Range (e.g., 99 for sample->value1).
• Decision: If stats$range is wide (e.g., 99 vs. avg 20), prepare for extreme weather conditions.

stats$sum

When to Use: Aggregating totals, such as total sales revenue over a period.

• Example: A retailer sums daily sales in sample->value1 across 100 stores.
• Returned Value: The total (e.g., 5050 for sample->value1).
• Decision: If the stats$sum exceeds targets (e.g., $5050 vs. $5000 goal), allocate bonuses or expand inventory.

stats$mean

When to Use: Measuring central tendency, such as average customer wait time in a call center.

• Example: A manager evaluates 100 call durations in sample->value1.
• Returned Value: The arithmetic mean (e.g., 50.5 for sample->value1).
• Decision: If the stats$mean is high (e.g., 50.5 minutes vs. 30-minute target), hire more staff or streamline processes.

stats$median

When to Use: Robust central tendency, such as median home prices.

• Example: A realtor analyzes 100 sales in sample->value1.
• Returned Value: Middle value (e.g., 50.5 for sample->value1). With an EVEN number of values, the exact average of the two middle values — computed in exact REAL arithmetic, so it agrees with Excel, R, and Python.
• Decision: If stats$median lags market (e.g., $200K vs. $250K), adjust pricing strategies.

stats$mode

When to Use: Most common value, such as popular product size.

• Example: A retailer analyzes 100 shoe sales in sample->value1.
• Returned Value: Mode (e.g., 1 for sample->value1; when several values tie for most frequent—as here, where every value occurs once—the SMALLEST of them is returned).
• Decision: If stats$mode is size 8, stock more of that size.

stats$midrange

When to Use: Simple central estimate, like average of extremes in test scores.

• Example: A teacher analyzes 100 scores in sample->value1.
• Returned Value: Midrange (e.g., 50.5 for sample->value1).
• Decision: If stats$midrange deviates from mean (e.g., 50.5 vs. 60), check for skewed data.

Dispersion & Distribution Metrics

stats$stddev

When to Use: Assessing variability, such as consistency of product weights in manufacturing.

• Example: A factory tests 100 widget weights in sample->value1.
• Returned Value: SAMPLE standard deviation (e.g., ~29.01 for sample->value1). Pass 1 as a 2nd argument for the POPULATION form: stats$stddev(sample->value1, 1) gives ~28.87. The two answer different questions—know which one you are asking.
• Decision: If stats$stddev is high (e.g., 29 vs. target 5), tighten quality control to reduce variation.

stats$var

When to Use: Quantifying spread, such as volatility of investment returns.

• Example: A portfolio manager analyzes 100 daily returns in sample->value1.
• Returned Value: Variance (e.g., ~841.67 for sample->value1).
• Decision: If stats$var is excessive (e.g., 841 vs. 100 benchmark), diversify investments to lower risk.

stats$sem

When to Use: Reporting how precisely a mean is known — the ± on a measured average.

• Example: A lab reports the average of 100 readings in sample->value1.
• Returned Value: The standard error of the mean: sample standard deviation / √n (e.g., ~2.90 for sample->value1). As a rule of thumb, the true mean lies within ±2 SEM of the sample mean about 95% of the time.
• Decision: If the SEM is too wide for the claim you want to make, collect more data — quadrupling the row count halves the SEM.

stats$iqr

When to Use: Measuring middle 50% spread, such as income variability.

• Example: A researcher analyzes 100 incomes in sample->value1.
• Returned Value: IQR (e.g., 49.5 for sample->value1).
• Decision: If stats$iqr is large (e.g., 50 vs. 20 norm), address income inequality or outliers.

stats$cv

When to Use: Relative variability, such as comparing consistency across datasets.

• Example: A quality analyst compares 100 measurements in sample->value1.
• Returned Value: Coefficient of variation as a RATIO, not a percent (e.g., ~0.574 for sample->value1; multiply by 100 yourself for a percent). Computed on |mean|; a zero mean raises msg_nostatistic.
• Decision: If stats$cv is high (e.g., 57% vs. 10% target), improve process stability.

stats$mad

When to Use: Robust measure of spread, like variability in noisy data.

• Example: A scientist analyzes 100 sensor readings in sample->value1.
• Returned Value: Median Absolute Deviation (e.g., 25 for sample->value1). This is the RAW MAD—no 1.4826 normal-consistency scaling is applied; multiply yourself if you want a robust stddev estimate.
• Decision: If stats$mad is high (e.g., 25 vs. 5 target), filter outliers or adjust sensors.

Percentiles & Risk Measures

stats$percentile(50)

When to Use: Finding a specific quantile, such as median income in a survey.

• Example: A sociologist studies 100 household incomes in sample->value1.
• Returned Value: 50th percentile (e.g., 50.5 for sample->value1), linearly interpolated. The exact method: the position is p/100 × (n−1) on the sorted values, with linear interpolation between the two neighbors when it falls between them — the same definition as Excel's PERCENTILE.INC, NumPy's default, and R's type 7, so those tools agree with Sheerpower to the digit (P25 of 1,2,3,4 is 1.75). The position arithmetic is exact, never a rounded double. stats$iqr is P75 − P25 under this same method. The percentile argument may be FRACTIONAL: stats$percentile(sample->value1, 2.5) and 97.5 give the classic 95% band edges, under the same exact interpolation. Out of range (below 0 or above 100) raises msg_num_outofrange.
• Decision: If stats$percentile(50) is low (e.g., $50K vs. $60K norm), advocate for wage increases.

stats$zscore(50)

When to Use: Standardizing data, such as identifying outliers in test scores.

• Example: A researcher checks a score of 50 in sample->value1 (100 results).
• Returned Value: Z-score (e.g., -0.0172 for sample->value1), always computed against the SAMPLE standard deviation.
• Decision: If stats$zscore is extreme (e.g., > 3), flag as an outlier for review.

stats$drawdown

When to Use: Measuring peak-to-trough decline, such as maximum loss in a trading account.

• Example: A trader tracks portfolio value in sample->value1 over 100 days.
• Returned Value: Max drawdown as a POSITIVE number: the largest peak-to-trough decline, expressed as a FRACTION of the peak (0.25 = a 25% drop) whenever the peak is positive — the usual case for price series. If the running peak is zero or negative, the absolute decline is used instead. (E.g., 0 for sample->value1 since it's increasing.)
• Decision: If stats$drawdown is high (e.g., 50% in a real portfolio), adjust risk management (e.g., stop-loss orders).

stats$vrisk(0.95)

When to Use: Risk assessment, such as Value at Risk for portfolio losses.

• Example: A fund manager assesses 100 daily returns in sample->value1.
• Returned Value: The value at the (1−c) tail of the data, WITH ITS OWN SIGN — on a returns series a 95% VaR of −0.07 means the cutoff return is a 7% loss (the function does not flip it to a positive “loss amount”; both conventions exist in finance, and Sheerpower returns the tail value itself). The confidence level is a FRACTION (0.95, not 95). vrisk uses the NEAREST-RANK convention (the conservative choice), so it deliberately differs from stats$percentile's interpolation on the same data.
• Decision: If stats$vrisk is a deep loss (e.g., −0.10 = a 10% loss at the cutoff), reduce exposure or hedge positions.

stats$cvrisk(0.95)

When to Use: Expected shortfall, such as average loss beyond VaR in finance.

• Example: Same fund manager as above, using sample->value1.
• Returned Value: CVaR — the mean of the values at or below the VaR cutoff, with the SAME sign convention as vrisk (the tail values themselves, not a positive loss amount). Confidence level is a fraction, like vrisk.
• Decision: If stats$cvrisk is severe (e.g., −0.15 = the average tail loss is 15%), increase cash reserves or diversify.

Skewness & Kurtosis (Shape of Distribution)

stats$skew

When to Use: Checking distribution symmetry, such as customer purchase amounts.

• Example: An e-commerce analyst studies 100 transactions in sample->value1.
• Returned Value: POPULATION skewness (e.g., 0 for sample->value1, uniform). For the sample (G1) estimator, use stats$fpskew_sample.
• Decision: If stats$skew is positive (e.g., 2, many small purchases, few large), target high-spenders with promotions.

stats$kurtosis

When to Use: Evaluating tail heaviness, such as risk of extreme events in insurance claims.

• Example: An insurer analyzes 100 claim sizes in sample->value1.
• Returned Value: POPULATION EXCESS kurtosis—3 is already subtracted, so a normal distribution scores 0 (e.g., ~-1.2002 for sample->value1; flat distributions are negative).
• Decision: If stats$kurtosis is high (e.g., 3, heavy tails), reserve more capital for rare, large claims.

stats$skew_sample

When to Use: Measuring sample skewness, like asymmetry in production times.

• Example: A factory analyzes 100 cycle times in sample->value1.
• Returned Value: Fisher-Pearson SAMPLE skewness, the G1 estimator (e.g., 0 for sample->value1). Estimates the same quantity as stats$skew with a small-sample correction. (stats$fpskew_sample is the same function under its original name — the “fp” stands for Fisher-Pearson — and remains accepted.)
• Decision: If stats$skew_sample is high (e.g., 1.5), investigate process bias or delays.

stats$kurtosis_sample

When to Use: Assessing sample tail weight, like defect rates in quality control.

• Example: A QA team checks 100 defect counts in sample->value1.
• Returned Value: Sample EXCESS kurtosis, the G2 estimator (e.g., -1.2 for sample->value1). Estimates the same quantity as stats$kurtosis with a small-sample correction; both are near -1.2 for this uniform ramp.
• Decision: If stats$kurtosis_sample is high (e.g., > 3), prepare for rare, severe defects.

Alternative Measures of Central Tendency

stats$gmean

When to Use: Growth rates, such as average investment return over time.

• Example: An investor tracks 100 daily returns in sample->value1.
• Returned Value: Geometric mean (e.g., ~37.99 for sample->value1).
• Decision: If stats$gmean is low (e.g., 2% vs. 5% target), reassess investment strategy.

stats$hmean

When to Use: Rates or averages with inverses, such as average speed over distances.

• Example: A logistics firm measures 100 delivery speeds in sample->value1.
• Returned Value: Harmonic mean (e.g., ~19.28 for sample->value1).
• Decision: If stats$hmean is slow (e.g., 20 mph vs. 30 mph goal), optimize routes.

Statistical Tests & Inference

stats$ttest

When to Use: Comparing means, such as A/B testing website conversion rates.

• Example: A marketer tests two ad campaigns (sample->value1 vs. sample->value2, 100 clicks each).
• Returned Value: WELCH's t-statistic (unequal variances assumed; e.g., 0 for sample->value1 vs. sample->value2, equal means). The two-sided P-VALUE is returned as a second result in _real (Welch–Satterthwaite degrees of freedom): read it right after the call.
• Decision: Judge significance by the p-value in _real, not by the size of t alone — whether a given t is significant depends on the sample sizes. If the p-value is below your significance level (e.g., < 0.05), the means genuinely differ; a p-value near 1 means no detectable difference.

stats$ttest_paired

When to Use: Before/after comparisons on the SAME subjects — each row pairs two measurements of one thing.

• Example: 100 patients' blood pressure before (sample->value1) and after (sample->value2) treatment.
• Returned Value: The paired t-statistic, computed on the row-by-row differences (df = n − 1). The two-sided P-VALUE is returned as a second result in _real: read it right after the call. Rows must line up — both columns come from the same cluster with equal counts.
• Decision: Reach for the PAIRED test when rows are naturally linked (same person, same machine, same day): it cancels between-subject variation, so it detects smaller effects than stats$ttest would on the same data. A p-value below your significance level means the treatment genuinely changed the measurement.

stats$chi2

When to Use: Goodness-of-fit, such as testing observed vs. expected frequencies.

• Example: A biologist compares 100 observed gene frequencies in sample->value1 vs. expected in sample->value2.
• Returned Value: Chi-squared goodness-of-fit statistic (var1 = observed, var2 = expected; df = n - 1). The P-VALUE is returned as a second result in _real: read it right after the call.
• Decision: If the p-value in _real is below your significance level (e.g., < 0.05), reject the null hypothesis (data doesn't fit the expected distribution).

stats$ftest

When to Use: Variance comparison, such as consistency of two machines.

• Example: A factory tests output variance from two lines (sample->value1 vs. sample->value2, 100 units each).
• Returned Value: F-statistic, always the LARGER variance over the smaller, so F >= 1 (e.g., 1 for sample->value1 vs. sample->value2, identical spreads). The P-VALUE is returned in _real.
• Decision: If the p-value in _real is below your significance level, one machine is less consistent—repair or replace.

Regression & Correlation

stats$linreg

When to Use: Linear relationship, such as sales vs. ad spend.

• Example: A marketer correlates 100 days of spend (sample->value1) and sales (sample->value2).
• Returned Value: Slope (e.g., -1 for sample->value1 vs. sample->value2). The INTERCEPT is returned as a second result in _real (e.g., 101 here, since value2 = 101 - value1): read it right after the call.
• Decision: If stats$linreg slope is positive and steep (e.g., 2), increase ad budget.

stats$linreg_r2

When to Use: How well the regression line actually fits — the fraction of variation in y explained by x.

• Example: After stats$linreg(spend, sales) gives the slope, ask stats$linreg_r2(spend, sales) whether the line is trustworthy.
• Returned Value: R-squared, 0 to 1 — the squared Pearson correlation, computed exactly (1 for a perfect linear relationship, 0 for none).
• Decision: A steep slope with a low R² (e.g., < 0.3) means the line explains little — don't bet the budget on it. Slope, intercept (_real after stats$linreg), and R² together are the whole story of a simple regression.

stats$pcorr

When to Use: Normalized correlation, such as temperature vs. ice cream sales.

• Example: A vendor analyzes 100 days of data (sample->value1 vs. sample->value2).
• Returned Value: Pearson correlation (e.g., -1 for sample->value1 vs. sample->value2).
• Decision: If stats$pcorr is high positive (e.g., 0.9), stock more ice cream on hot days.

stats$spearman

When to Use: Rank correlation, such as student test scores vs. study hours.

• Example: A teacher compares 100 students' ranks in sample->value1 vs. sample->value2.
• Returned Value: Spearman's rho with proper tie handling (e.g., -1 for sample->value1 vs. sample->value2, a perfect inverse ranking).
• Decision: If stats$spearman rho is high (e.g., 0.8), study hours strongly predict scores—encourage study time.

stats$cov

When to Use: Relationship strength, such as stock price correlations.

• Example: A trader compares two stocks over 100 days (sample->value1 vs. sample->value2).
• Returned Value: Covariance (e.g., -841.67 for sample->value1 vs. sample->value2).
• Decision: If stats$cov is negative (e.g., -841), diversify with inversely related assets.

Finance & Risk Analysis

stats$sharpe(0)

When to Use: Risk-adjusted return, such as portfolio performance.

• Example: An investor evaluates 100 daily returns in sample->value1.
• Returned Value: Sharpe ratio (e.g., ~1.74 for sample->value1). The exact formula: (mean − risk_free) divided by the SAMPLE standard deviation, with NO annualization — the ratio is in whatever period your data is in (daily returns give a daily Sharpe). You own the period conversion; daily, monthly, and annual Sharpe ratios are not interchangeable.
• Decision: If stats$sharpe is low (e.g., < 1), shift to less volatile assets.

stats$cagr

When to Use: Compound growth, such as investment growth rate.

• Example: A financial analyst tracks a fund over 2 years in sample->value1 (100 periods).
• Returned Value: CAGR as a FRACTION: (last/first)^1/years − 1, computed from the first and last values. A return of 0.09 means 9% growth per year; the example dataset (1 → 100 over 2 years) returns 9 — that is 900% per year, which is what a hundredfold gain in two years really is. Rates as fractions compose naturally with arithmetic (value * (1 + cagr)).
• Decision: If stats$cagr beats the benchmark (e.g., 0.09 vs. 0.05), recommend the fund.

stats$rms

When to Use: Measuring magnitude, like volatility in financial time series.

• Example: A trader assesses 100 daily prices in sample->value1.
• Returned Value: Root Mean Square (e.g., ~58.17 for sample->value1).
• Decision: If stats$rms is high (e.g., 60 vs. 20 norm), reduce position size to manage volatility.

Additional Functions (August 2026)

Nine more functions became callable in August 2026. Values shown are for the same sample cluster.

stats$moment(n)

When to Use: Custom distribution analysis — the Nth central moment is the raw material skewness and kurtosis are built from.

• Example: A researcher probes the shape of 100 measurements with stats$moment(sample->value1, 3).
• Returned Value: The Nth central moment, mean((x − mean)ⁿ) (e.g., 0 for the 3rd moment of this symmetric ramp; the 2nd moment is the population variance).
• Decision: A nonzero odd moment signals asymmetry; for standard shape questions reach for stats$skew/stats$kurtosis instead, which normalize the moments for you.

stats$trimmed_mean(10)

When to Use: An outlier-resistant average, such as judging scores or delivery times with occasional extremes.

• Example: An operations analyst averages 100 delivery times after discarding the fastest and slowest 10%: stats$trimmed_mean(sample->value1, 10).
• Returned Value: The mean after trimming that percentage from EACH end (e.g., 50.5 here — trimming a symmetric set does not move its center). The percentage is optional.
• Decision: If the trimmed mean differs sharply from stats$mean, outliers are driving the plain average — investigate them before acting on it.

stats$weighted_mean

When to Use: An average where some rows matter more — portfolio returns weighted by position size, grades weighted by credits.

• Example: A registrar computes a GPA: stats$weighted_mean(sample->value1, sample->value2) — value1 weighted by value2.
• Returned Value: sum(value × weight) / sum(weight) (exactly 34 here — the small values carry the large weights).
• Decision: When the weighted mean and the plain mean disagree, the heavy-weight rows are pulling the result — make sure the weights reflect what you intend them to.

stats$ema(0.1)

When to Use: A recency-weighted average, such as smoothing a price series or sensor feed where the latest readings matter most.

• Example: A trader smooths 100 prices with stats$ema(sample->value1, 0.1) (alpha 0.1 = gentle smoothing; larger alpha reacts faster).
• Returned Value: The FINAL exponentially smoothed value after walking the whole series in row order (~91.0 here, trailing the rising ramp).
• Decision: If the latest value sits far above its EMA, the series is breaking upward from its recent trend (and vice versa) — a classic signal line.

stats$autocorr

When to Use: Detecting trend or seasonality — does the series remember its own past?

• Example: A forecaster checks whether daily sales predict the next day: stats$autocorr(sample->value1) (lag 1; pass a second argument for other lags, e.g. 7 for weekly patterns).
• Returned Value: The autocorrelation at the given lag, −1 to 1 (1 for this perfectly trending ramp; near 0 for white noise).
• Decision: High autocorrelation means yesterday predicts today — forecasting helps and trends persist; near zero means each period stands alone.

stats$rank(25)

When to Use: Where one observation stands among all of them, such as a student's standing in a class.

• Example: Where does row 25's value rank? stats$rank(sample->value1, 25).
• Returned Value: The 1-origin rank of that row's value, smallest = 1 (25 here, since the column is already sorted); TIED values share their average rank. The row argument is an ordinary CLUSTER row number.
• Decision: A rank in the top decile of costs, times, or error counts marks the row for attention.

stats$cdf(1.5, 10)

When to Use: Turning a CHI-SQUARE statistic into a probability by hand — the distribution function behind stats$chi2.

• Example: What fraction of the chi-square distribution with 10 degrees of freedom lies below 1.5? stats$cdf(1.5, 10).
• Returned Value: The chi-square CDF (~0.0011 here). Takes PLAIN NUMBERS, not a cluster column — and therefore no collection flag.
• Decision: 1 − cdf is the p-value of a chi-square statistic; below your significance level, reject the null. (After stats$chi2 itself, just read _real instead.)

stats$fcdf(2, 10, 20)

When to Use: Turning an F statistic into a probability by hand — the distribution function behind stats$ftest.

• Example: How much of the F(10, 20) distribution lies below 2? stats$fcdf(2, 10, 20).
• Returned Value: The F-distribution CDF (~0.9102 here). Plain numbers; no collection flag.
• Decision: 1 − fcdf is a one-sided p-value for an F statistic. (After stats$ftest itself, read _real instead.)

stats$ncdf(1.96)

When to Use: Turning a z-score into a probability — the standard normal (bell curve) distribution function.

• Example: What fraction of a standard normal distribution lies below 1.96? stats$ncdf(1.96).
• Returned Value: The normal CDF (~0.9750 here). Takes a PLAIN NUMBER, not a cluster column — and therefore no collection flag. Pair it with stats$zscore to turn a z-score into a percentile.
• Decision: 2 × (1 − ncdf(|z|)) is the two-sided p-value of a z-score; below your significance level, the observation is genuinely unusual.

stats$tcdf(2.1, 10)

When to Use: Turning a t-statistic into a probability by hand — the distribution function behind stats$ttest and stats$ttest_paired.

• Example: How much of the t distribution with 10 degrees of freedom lies below 2.1? stats$tcdf(2.1, 10).
• Returned Value: The Student-t CDF (~0.969 here). Plain numbers; no collection flag. With large df it converges to stats$ncdf.
• Decision: 2 × (1 − tcdf(|t|, df)) is the two-sided p-value of a t statistic. (After the t-test functions themselves, just read _real.)

stats$ks_test

When to Use: A quick normality check before leaning on tools that assume a bell curve.

• Example: Are 100 measurement errors normally distributed? stats$ks_test(sample->value1).
• Returned Value: The Kolmogorov–Smirnov D statistic against a NORMAL distribution fitted to the sample's own mean and standard deviation (~0.061 here). The P-VALUE is returned in _real (~0.839 here): read it right after the call. Because the reference normal is fitted from the sample itself, this classical p-value reads a little HIGH (conservative)—a strict normality test would use the Lilliefors distribution.
• Decision: A small p-value (e.g., < 0.05) says the data is NOT normal — prefer robust statistics (stats$median, stats$mad, stats$trimmed_mean) over mean-and-stddev reasoning.