math::statistics(n)

📦

version 2.0 · 2 versions

2.0 · fedora 43, fedora 44, nixos 26.05, nixpkgs unstable (latest)
1.21 · alpine 3.24, epel 9, opensuse-leap 16.0

, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

💖 math::statistics 💖 — Basic statistical functions and procedures

okay so bestie, welcome to math::statistics(n) from the Tcl Math Library 🎀 this is the page where all the stats magic lives and honestly? it's giving main character energy. it's long, it's juicy, and we're doing it in 8 parts. buckle up 💅

✨ SYNOPSIS ✨

first things first, the requirements, no cap:

package require Tcl 8.5 9

package require math::statistics 1.6.1

and now the full roster of procs, in order, every single one, because we don't skip anyone in this house 🫶

::math::statistics::mean data

::math::statistics::min data

::math::statistics::max data

::math::statistics::number data

::math::statistics::stdev data

::math::statistics::var data

::math::statistics::pstdev data

::math::statistics::pvar data

::math::statistics::median data

::math::statistics::basic-stats data

::math::statistics::histogram limits values ?weights?

::math::statistics::histogram-alt limits values ?weights?

::math::statistics::corr data1 data2

::math::statistics::interval-mean-stdev data confidence

::math::statistics::t-test-mean data est_mean est_stdev alpha

::math::statistics::test-normal data significance

::math::statistics::lillieforsFit data

::math::statistics::test-Duckworth list1 list2 significance

::math::statistics::test-anova-F alpha args

::math::statistics::test-Tukey-range alpha args

::math::statistics::test-Dunnett alpha control args

::math::statistics::quantiles data confidence

::math::statistics::quantiles limits counts confidence

::math::statistics::autocorr data

::math::statistics::crosscorr data1 data2

::math::statistics::mean-histogram-limits mean stdev number

::math::statistics::minmax-histogram-limits min max number

::math::statistics::linear-model xdata ydata intercept

::math::statistics::linear-residuals xdata ydata intercept

::math::statistics::test-2x2 n11 n21 n12 n22

::math::statistics::print-2x2 n11 n21 n12 n22

::math::statistics::control-xbar data ?nsamples?

::math::statistics::control-Rchart data ?nsamples?

::math::statistics::test-xbar control data

::math::statistics::test-Rchart control data

::math::statistics::test-Kruskal-Wallis confidence args

::math::statistics::analyse-Kruskal-Wallis args

::math::statistics::test-Levene groups

::math::statistics::test-Brown-Forsythe groups

::math::statistics::group-rank args

::math::statistics::test-Wilcoxon sample_a sample_b

::math::statistics::spearman-rank sample_a sample_b

::math::statistics::spearman-rank-extended sample_a sample_b

::math::statistics::kernel-density data opt -option value ...

::math::statistics::bootstrap data sampleSize ?numberSamples?

::math::statistics::wasserstein-distance prob1 prob2

::math::statistics::kl-divergence prob1 prob2

::math::statistics::logistic-model xdata ydata

::math::statistics::logistic-probability coeffs x

::math::statistics::tstat dof ?alpha?

::math::statistics::mv-wls weights_and_values

::math::statistics::mv-ols values

::math::statistics::pdf-normal mean stdev value

::math::statistics::pdf-lognormal mean stdev value

::math::statistics::pdf-exponential mean value

::math::statistics::pdf-uniform xmin xmax value

::math::statistics::pdf-triangular xmin xmax value

::math::statistics::pdf-symmetric-triangular xmin xmax value

::math::statistics::pdf-gamma alpha beta value

::math::statistics::pdf-poisson mu k

::math::statistics::pdf-chisquare df value

::math::statistics::pdf-student-t df value

::math::statistics::pdf-gamma a b value

::math::statistics::pdf-beta a b value

::math::statistics::pdf-weibull scale shape value

::math::statistics::pdf-gumbel location scale value

::math::statistics::pdf-pareto scale shape value

::math::statistics::pdf-cauchy location scale value

::math::statistics::pdf-laplace location scale value

::math::statistics::pdf-kumaraswamy a b value

::math::statistics::pdf-negative-binomial r p value

::math::statistics::cdf-normal mean stdev value

::math::statistics::cdf-lognormal mean stdev value

::math::statistics::cdf-exponential mean value

::math::statistics::cdf-uniform xmin xmax value

::math::statistics::cdf-triangular xmin xmax value

::math::statistics::cdf-symmetric-triangular xmin xmax value

::math::statistics::cdf-students-t degrees value

::math::statistics::cdf-gamma alpha beta value

::math::statistics::cdf-poisson mu k

::math::statistics::cdf-beta a b value

::math::statistics::cdf-weibull scale shape value

::math::statistics::cdf-gumbel location scale value

::math::statistics::cdf-pareto scale shape value

::math::statistics::cdf-cauchy location scale value

::math::statistics::cdf-F nf1 nf2 value

::math::statistics::cdf-laplace location scale value

::math::statistics::cdf-kumaraswamy a b value

::math::statistics::cdf-negative-binomial r p value

::math::statistics::empirical-distribution values

::math::statistics::random-normal mean stdev number

::math::statistics::random-lognormal mean stdev number

::math::statistics::random-exponential mean number

::math::statistics::random-uniform xmin xmax number

::math::statistics::random-triangular xmin xmax number

::math::statistics::random-symmetric-triangular xmin xmax number

::math::statistics::random-gamma alpha beta number

::math::statistics::random-poisson mu number

::math::statistics::random-chisquare df number

::math::statistics::random-student-t df number

::math::statistics::random-beta a b number

::math::statistics::random-weibull scale shape number

::math::statistics::random-gumbel location scale number

::math::statistics::random-pareto scale shape number

::math::statistics::random-cauchy location scale number

::math::statistics::random-laplace location scale number

::math::statistics::random-kumaraswamy a b number

::math::statistics::random-negative-binomial r p number

::math::statistics::histogram-uniform xmin xmax limits number

::math::statistics::incompleteGamma x p ?tol?

::math::statistics::incompleteBeta a b x ?tol?

::math::statistics::estimate-pareto values

::math::statistics::estimate-exponential values

::math::statistics::estimate-laplace values

::math::statistics::estimante-negative-binomial r values

::math::statistics::filter varname data expression

::math::statistics::map varname data expression

::math::statistics::samplescount varname list expression

::math::statistics::subdivide

::math::statistics::plot-scale canvas xmin xmax ymin ymax

::math::statistics::plot-xydata canvas xdata ydata tag

::math::statistics::plot-xyline canvas xdata ydata tag

::math::statistics::plot-tdata canvas tdata tag

::math::statistics::plot-tline canvas tdata tag

::math::statistics::plot-histogram canvas counts limits tag

like, that's the whole lineup 🔥 and yes estimante-negative-binomial is spelled exactly like that, we don't touch it, it's canon now 💀

🌸 DESCRIPTION 🌸

so the math::statistics package is a whole toolbox of functions and procedures for doing basic statistical data analysis, stuff like:

Descriptive statistical parameters (mean, minimum, maximum, standard deviation) — the classic squad 💅
Estimates of the distribution in the form of histograms and quantiles
Basic testing of hypotheses
Probability and cumulative density functions

it's here to help you build data analysis applications or just do some ad hoc data analysis on the fly. but real talk: it is not in itself a full application, and it is not trying to rival full (non-)commercial statistical packages. it's your bestie, not your entire stats department 😌

the purpose of this document is to describe the implemented procedures and give you some examples of how to use them. there's ample literature on the algorithms involved, so for the deep lore we point you at the relevant text books 📚 the package contains a fairly large number of public procedures, and they split into three sets:

general procedures
procedures that deal with specific statistical distributions
list procedures to select or transform data

plus simple plotting procedures (these ones require Tk).

Note: the data that need to be analyzed are always contained in a simple list. Missing values are represented as empty list elements. 🕳️

Note: with version 1.0.1 a mistake in the procs pdf-lognormal, cdf-lognormal and random-lognormal has been corrected. In previous versions the argument for the standard deviation was actually used as if it was the variance. so if you were on an old version… that's why your numbers were weird, bestie, it wasn't you 😭

🧚 GENERAL PROCEDURES 🧚

the general statistical procedures are:

`::math::statistics::mean data`

Determine the mean value of the given list of data.

list data — List of data

`::math::statistics::min data`

Determine the minimum value of the given list of data.

list data — List of data

`::math::statistics::max data`

Determine the maximum value of the given list of data.

list data — List of data

`::math::statistics::number data`

Determine the number of non-missing data in the given list.

list data — List of data

`::math::statistics::stdev data`

Determine the sample standard deviation of the data in the given list.

list data — List of data

`::math::statistics::var data`

Determine the sample variance of the data in the given list.

list data — List of data

`::math::statistics::pstdev data`

Determine the population standard deviation of the data in the given list.

list data — List of data

`::math::statistics::pvar data`

Determine the population variance of the data in the given list.

list data — List of data

`::math::statistics::median data`

Determine the median of the data in the given list. (heads up: this requires sorting the data, which may be a costly operation — it's the diva of the group, she takes her time 💅)

list data — List of data

`::math::statistics::basic-stats data`

Determine a list of all the descriptive parameters: mean, minimum, maximum, number of data, sample standard deviation, sample variance, population standard deviation and population variance. one-stop shop, obsessed ✨

(this routine is called whenever either or all of the basic statistical parameters are required. hence all calculations are done and the relevant values are returned.)

list data — List of data

`::math::statistics::histogram limits values ?weights?`

Determine histogram information for the given list of data. Returns a list consisting of the number of values that fall into each interval. (the first interval consists of all values lower than the first limit, the last interval consists of all values greater than the last limit. there is one more interval than there are limits — yes really, count them twice, it's true 🧠)

Optionally, you can use weights to influence the histogram.

list limits — the upper limits for the histogram intervals, listed in ascending order bestie, they go up 📈
list values — the data, obviously 💅
list weights — a list of weights, one weight for every single value, no skips

`::math::statistics::histogram-alt limits values ?weights?`

An alternative take on the histogram procedure: the open end of the intervals sits at the lower bound instead of the upper bound. Same energy, different edge 🦋

list limits — list of upper limits (ascending order) for the histogram intervals.
list values — list of data.
list weights — list of weights, one weight per value.

`::math::statistics::corr data1 data2`

Find the correlation coefficient between two data sets. Do they move together or not, that's the vibe check 🔥

list data1 — first list of data.
list data2 — second list of data.

`::math::statistics::interval-mean-stdev data confidence`

Hands you back the interval that contains the mean, plus one that contains the standard deviation, at a certain level of confidence (it's assuming a normal distribution, just so you know 👑).

list data — list of raw data values (small sample).
float confidence — confidence level (like 0.95 or 0.99 for instance).

`::math::statistics::t-test-mean data est_mean est_stdev alpha`

Checks whether the mean of a sample lines up with the estimated normal distribution at a given probability. Returns 1 if the test succeeds, or 0 if the mean is unlikely to fit the distribution you gave it. ✨

list data — list of raw data values (small sample).
float est_mean — estimated mean of the distribution.
float est_stdev — estimated stdev of the distribution.
float alpha — probability level (like 0.95 or 0.99 for instance).

`::math::statistics::test-normal data significance`

Checks whether the data you gave it follow a normal distribution at a certain level of significance. Returns 1 if the data are normally distributed within that level of significance, returns 0 if not. The underlying test is the Lilliefors test. Heads up bestie: smaller values of the significance mean a stricter testing 😤

list data — list of raw data values.
float significance — significance level (one of 0.01, 0.05, 0.10, 0.15 or 0.20). For compatibility reasons the values "1-significance", 0.80, 0.85, 0.90, 0.95 or 0.99 are also accepted.

Compatibility issue: the original implementation and documentation used the term "confidence" and used a value 1-significance (see ticket 2812473fff). This has been corrected as of version 0.9.3. 💀

`::math::statistics::lillieforsFit data`

Returns the goodness of fit to a normal distribution according to Lilliefors. The higher the number, the more likely the data are indeed normally distributed. The test requires at least five data points. Don't try it with four, it will simply not eat. 🙈

list data — list of raw data values.

`::math::statistics::test-Duckworth list1 list2 significance`

Determine if two data sets have the same median according to the Tukey-Duckworth test. The procedure returns 0 if the medians are unequal, 1 if they are equal, -1 if the test can not be conducted (the smallest value must be in a different set than the greatest value).

#
# Arguments:
#     list1           Values in the first data set
#     list2           Values in the second data set
#     significance    Significance level (either 0.05, 0.01 or 0.001)
#
# Returns: Test whether the given data follow a normal
distribution with a certain level of significance.  Returns 1 if
the data are normally distributed within the level of
significance, returns 0 if not. The underlying test is the
Lilliefors test. Smaller values of the significance mean a
stricter testing.

list list1 — first list of data.
list list2 — second list of data.
float significance — significance level (either 0.05, 0.01 or 0.001).

`::math::statistics::test-anova-F alpha args`

Determine if two or more groups of normally distributed data have the same means. The procedure returns 0 if the means are likely unequal, 1 if they are. This is a one-way ANOVA test. The groups may also be stored in a nested list: The procedure returns a list of the comparison results for each pair of groups. Each element of this list contains: the index of the first group and that of the second group, whether the means are likely to be different (1) or not (0) and the confidence interval the conclusion is based on. The groups may also be stored in a nested list:

test-anova-F 0.05 $A $B $C
#
# Or equivalently:
#
test-anova-F 0.05 [list $A $B $C]

float alpha — significance level.
list args — two or more groups of data to be checked.

`::math::statistics::test-Tukey-range alpha args`

Determine if two or more groups of normally distributed data have the same means, using Tukey's range test. It is complementary to the ANOVA test 🫶 The procedure returns a list of the comparison results for each pair of groups. Each element of this list contains: the index of the first group and that of the second group, whether the means are likely to be different (1) or not (0) and the confidence interval the conclusion is based on. The groups may also be stored in a nested list, just as with the ANOVA test.

float alpha — significance level — either 0.05 or 0.01.
list args — two or more groups of data to be checked.

`::math::statistics::test-Dunnett alpha control args`

Determine if one or more groups of normally distributed data have the same means as the group of control data, using Dunnett's test. It is complementary to the ANOVA test. The procedure returns a list of the comparison results for each group with the control group. Each element of this list contains: whether the means are likely to be different (1) or not (0) and the confidence interval the conclusion is based on. The groups may also be stored in a nested list, just as with the ANOVA test.

Note: some care is required if there is only one group to compare the control with:

test-Dunnett-F 0.05 $control [list $A]

Otherwise the group A is split up into groups of one element — this is due to an ambiguity. 😭

float alpha — significance level — either 0.05 or 0.01.
list args — one or more groups of data to be checked.

`::math::statistics::quantiles data confidence`

Return the quantiles for a given set of data 🌸

list data — list of raw data values.
float confidence — confidence level (like 0.95 or 0.99 for instance) or a list of confidence levels.

`::math::statistics::quantiles limits counts confidence`

Return the quantiles based on histogram information (this is the alternative to the call with two arguments, iykyk 👑).

list limits — list of upper limits from histogram.
list counts — list of counts for for each interval in histogram.
float confidence — confidence level (like 0.95 or 0.99 for instance) or a list of confidence levels.

`::math::statistics::autocorr data`

Return the autocorrelation function as a list of values (assuming equidistance between samples, about 1/2 of the number of raw data) 🦋

The correlation is determined in such a way that the first value is always 1 and all others are equal to or smaller than 1. The number of values involved will diminish as the "time" (the index in the list of returned values) increases.

list data — raw data for which the autocorrelation must be determined.

`::math::statistics::crosscorr data1 data2`

Return the cross-correlation function as a list of values (assuming equidistance between samples, about 1/2 of the number of raw data) ✨

The correlation is determined in such a way that the values can never exceed 1 in magnitude. The number of values involved will diminish as the "time" (the index in the list of returned values) increases.

list data1 — first list of data.
list data2 — second list of data.

`::math::statistics::mean-histogram-limits mean stdev number`

Determine reasonable limits based on mean and standard deviation for a histogram. Convenience function — the result is suitable for the histogram function 💅

float mean — mean of the data.
float stdev — standard deviation.
int number — number of limits to generate (defaults to 8).

`::math::statistics::minmax-histogram-limits min max number`

Determine reasonable limits based on a minimum and maximum for a histogram.

Convenience function — the result is suitable for the histogram function.

float min — expected minimum.
float max — expected maximum.
int number — number of limits to generate (defaults to 8).

`::math::statistics::linear-model xdata ydata intercept`

Determine the coefficients for a linear regression between two series of data (the model: Y = A + B*X). Returns a list of parameters describing the fit 🔥

list xdata — list of independent data.
list ydata — list of dependent data to be fitted.
boolean intercept — (Optional) compute the intercept (1, default) or fit to a line through the origin (0).

The result consists of the following list:

(Estimate of) Intercept A
(Estimate of) Slope B
Standard deviation of Y relative to fit

Correlation coefficient R2
Number of degrees of freedom df
Standard error of the intercept A
Significance level of A
Standard error of the slope B
Significance level of B

`::math::statistics::linear-residuals xdata ydata intercept`</p>

::math::statistics::linear-residuals xdata ydata intercept

Okay bestie, this one is giving "how wrong was my line actually?" energy 💅 — it figures out the difference between your real data and whatever the linear model predicted, no cap.

It hands you back a list of those differences (actual minus predicted, one for each point).

list xdata — the independent data, aka your x values.
list ydata — the dependent data you're fitting, aka your y values.
boolean intercept — (optional) do you want the intercept computed? Pass 1 to compute it (this is the default), or 0 to fit a line that goes straight through the origin. 🌸

`::math::statistics::test-2x2 n11 n21 n12 n22`

::math::statistics::test-2x2 n11 n21 n12 n22

So you've got two sets of samples, each one pulled from a binomial distribution, and you wanna know: do they actually differ in a meaningful way (aka a different parameter)? That's the vibe check this one runs. ✨

It returns the "chi-square" value, and you use that to suss out the significance.

int n11 — number of outcomes with the first value from the first sample.
int n21 — number of outcomes with the first value from the second sample.
int n12 — number of outcomes with the second value from the first sample.
int n22 — number of outcomes with the second value from the second sample.

`::math::statistics::print-2x2 n11 n21 n12 n22`

::math::statistics::print-2x2 n11 n21 n12 n22

Same exact energy as test-2x2 above — two samples from binomial distributions, do they differ significantly or not? — except this one is the ✨aesthetic✨ version.

It returns a short report, which is super handy when you're sitting in an interactive session and just want the tea without doing extra math. 🫶

int n11 — number of outcomes with the first value from the first sample.
int n21 — number of outcomes with the first value from the second sample.
int n12 — number of outcomes with the second value from the first sample.
int n22 — number of outcomes with the second value from the second sample.

`::math::statistics::control-xbar data ?nsamples?`

::math::statistics::control-xbar data ?nsamples?

Control chart girlies rise 👑 — this computes the control limits for an xbar chart. The number of data in each subsample defaults to 4. And listen, at least 20 subsamples are required. Not optional, that's the rule. 😭

It returns the mean, the lower limit, the upper limit, and the number of data per subsample.

list data — your list of observed data.
int nsamples — number of data per subsample.

`::math::statistics::control-Rchart data ?nsamples?`

::math::statistics::control-Rchart data ?nsamples?

The R-chart sibling to the xbar one 🦋 — this gives you the control limits for an R chart. The number of data in each subsample (nsamples) defaults to 4. And yeah, same deal: at least 20 subsamples are required.

It returns the mean range, the lower limit, the upper limit, and the number of data per subsample.

list data — your list of observed data.
int nsamples — number of data per subsample.

`::math::statistics::test-xbar control data`

::math::statistics::test-xbar control data

Did your data break out of the xbar chart control limits? 😳 This one checks exactly that.

It returns a list of subsamples — specifically their indices — that genuinely violated the limits. Snitch behavior, but make it statistics.

list control — the control limits as returned by the "control-xbar" procedure.
list data — your list of observed data.

`::math::statistics::test-Rchart control data`

::math::statistics::test-Rchart control data

Same energy, R chart edition 💜 — did the data go over the control limits?

It returns a list of subsamples — their indices — that actually violated the limits.

list control — the control limits as returned by the "control-Rchart" procedure.
list data — your list of observed data.

`::math::statistics::test-Kruskal-Wallis confidence args`

::math::statistics::test-Kruskal-Wallis confidence args

Kruskal-Wallis test time ✨ — this checks whether the population medians of two or more groups are equal, at a confidence level you choose.

float confidence — the confidence level you wanna use (between 0 and 1).
list args — two or more lists of data.

`::math::statistics::analyse-Kruskal-Wallis args`

::math::statistics::analyse-Kruskal-Wallis args

The math-y counterpart to the test above 🔥 — this one computes the statistical parameters for the Kruskal-Wallis test.

It returns the Kruskal-Wallis statistic and the probability that that value would occur, assuming the medians of the populations are equal.

list args — two or more lists of data.

`::math::statistics::test-Levene groups`

::math::statistics::test-Levene groups

Variance check incoming 📊 — this computes the Levene statistic to determine whether groups of data have the same variance (aka are homoscadastic) or not. The data are organised in groups.

This version uses the mean of the data as the measure to determine the deviations. The statistic is equivalent to an F statistic with degrees of freedom k-1 and N-k, where k is the number of groups and N is the total number of data.

list groups — list of groups of data.

`::math::statistics::test-Brown-Forsythe groups`

::math::statistics::test-Brown-Forsythe groups

Basically Levene's cooler cousin 🧚 — this computes the Brown-Forsythe statistic to figure out whether groups of data have the same variance (are homoscadastic) or not. Like the Levene test, but this version uses the median of the data. Periodt.

list groups — list of groups of data.

`::math::statistics::group-rank args`

::math::statistics::group-rank args

Ranking szn 💅 — this ranks the groups of data with respect to the complete set.

It returns a list with, for each data item, the group ID, the value, and the rank — which might be a rational number in case of ties. Yes bestie, ties happen, and this handles them properly.

list args — two or more lists of data.

`::math::statistics::test-Wilcoxon sample_a sample_b`

::math::statistics::test-Wilcoxon sample_a sample_b

Do these two samples have the same median or not? 👀 This computes the Wilcoxon test statistic to find out.

Fun fact, iykyk: the statistic can be regarded as standard normal if the sample sizes are both larger than 10.

It returns the value of this statistic.

list sample_a — list of data comprising the first sample.
list sample_b — list of data comprising the second sample.

`::math::statistics::spearman-rank sample_a sample_b`

::math::statistics::spearman-rank sample_a sample_b

Spearman rank correlation, the alternative to the ordinary (Pearson's) correlation coefficient 🌈. Heads up: the two samples should have the same number of data.

list sample_a — first list of data.
list sample_b — second list of data.

`::math::statistics::spearman-rank-extended sample_a sample_b`

::math::statistics::spearman-rank-extended sample_a sample_b

The deluxe version, no cap 👑 — Spearman rank correlation as an alternative to the ordinary (Pearson's) correlation coefficient, plus additional data. The two samples should have the same number of data.

The procedure returns the correlation coefficient, the number of data pairs used, and the z-score — an approximately standard normal statistic that tells you the significance of the correlation.

list sample_a — first list of data.
list sample_b — second list of data.

`::math::statistics::kernel-density data opt -option value ...`

::math::statistics::kernel-density data opt -option value ...

Kernel density estimation time, this one is iconic ✨ — it returns the density function based on kernel density estimation. The procedure is controlled by a small set of options, each of which gets a reasonable default.

The return value is three lists:

the centres of the bins
the associated probability density
a list of computational parameters (begin and end of the interval, mean and standard deviation, and the used bandwidth)

Those computational parameters can be used for further analysis. 🫶

list data — the data to be examined.
list args — option-value pairs:
- -weights weights — per data point the weight (default: 1 for all data).
- -bandwidth value — bandwidth to be used for the estimation (default: determined from standard deviation).
- -number value — number of bins to be returned (default: 100).
- -interval {begin end} — begin and end of the interval for which the density is returned (default: mean +/- 3*standard deviation).
- -kernel function — kernel to be used (one of: gaussian, cosine, epanechnikov, uniform, triangular, biweight, logistic; default: gaussian).

`::math::statistics::bootstrap data sampleSize ?numberSamples?`

::math::statistics::bootstrap data sampleSize ?numberSamples?

Bootstrap szn 🎀 — this creates a subsample (or subsamples) from a given list of data. The data in the samples are chosen from this list, and multiples may occur (yes, that's on purpose).

If there's only one subsample, the sample itself is returned (as a list of "sampleSize" values). Otherwise you get a list of samples back.

list data — list of values to choose from.
int sampleSize — number of values per sample.
int numberSamples — number of samples (default: 1).

`::math::statistics::wasserstein-distance prob1 prob2`

::math::statistics::wasserstein-distance prob1 prob2

Earth mover's distance, but make it statistics 🚚✨ — this computes the Wasserstein distance (aka earth mover's distance) for two equidistantly spaced histograms or probability densities.

The histograms don't need to be normalised to sum to one, but they must have the same number of entries.

Note: the histograms are assumed to be based on the same equidistant intervals. As the bounds are not passed, the value is expressed in the length of the intervals.

list prob1 — list of values for the first histogram/probability density.
list prob2 — list of values for the second histogram/probability density.

`::math::statistics::kl-divergence prob1 prob2`

::math::statistics::kl-divergence prob1 prob2

Kullback-Leibler divergence, the glow-up version of "how different are these two things" 💜 — this computes the KL divergence for two equidistantly spaced histograms or probability densities.

The histograms don't need to be normalised to sum to one, but they must have the same number of entries.

Note: the histograms are assumed to be based on the same equidistant intervals. As the bounds are not passed, the value is expressed in the length of the intervals.

list prob1 — list of values for the first histogram/probability density.
list prob2 — list of values for the second histogram/probability density.

⚠️ okay bestie listen up: the KL divergence is not symmetric, and the second histogram should not contain zeroes in places where the first histogram has non-zero values. That's not a vibe, that's a math crime. 🙈

list prob1 — List of values for the first histogram / probability density
list prob2 — List of values for the second histogram / probability density

✨ `::math::statistics::logistic-model` xdata ydata

Estimate the coefficients of the logistic model that fits the data best. The data consist of independent x-values and the outcome 0 or 1 for each of the x-values. The result can be used to estimate the probability that a certain x-value gives 1. Basically: does this thing pop off or flop, and how likely is each? 💅

list xdata — List of values for which the success (1) or failure (0) is known
list ydata — List of successes or failures corresponding to each value in xdata.

💫 `::math::statistics::logistic-probability` coeffs x

Calculate the probability of success for the value x, given the coefficients of the logistic model. It's giving "feed me the model, I'll tell you the odds." 🔮

list coeffs — List of coefficients as determine by the logistic-model command
float x — X-value for which the probability needs to be determined

🌈 MULTIVARIATE LINEAR REGRESSION 🌈

Besides the linear regression with a single independent variable, the statistics package provides two procedures for doing ordinary least squares (OLS) and weighted least squares (WLS) linear regression with several variables. They were written by Eric Kemp-Benedict. Shoutout king 👑

In addition to these two, it provides a procedure (tstat) for calculating the value of the t-statistic for the specified number of degrees of freedom that is required to demonstrate a given level of significance.

🚨 Note: These procedures depend on the math::linearalgebra package. No linearalgebra, no regression. Periodt.

📐 Description of the procedures

`::math::statistics::tstat` dof ?alpha?

Returns the value of the t-distribution *t** satisfying

P(t*)  =  1 - alpha/2
P(-t*) =  alpha/2

for the number of degrees of freedom dof.

Given a sample of normally-distributed data x, with an estimate xbar for the mean and sbar for the standard deviation, the alpha confidence interval for the estimate of the mean can be calculated as

( xbar - t* sbar , xbar + t* sbar)

The return values from this procedure can be compared to an estimated t-statistic to determine whether the estimated value of a parameter is significantly different from zero at the given confidence level. That's the whole vibe check fr fr. 🎀

int dof — Number of degrees of freedom
float alpha — Confidence level of the t-distribution. Defaults to 0.05.

🌸 `::math::statistics::mv-wls` weights_and_values

Carries out a weighted least squares linear regression for the data points provided, with weights assigned to each point.

The linear model is of the form

y = b0 + b1 * x1 + b2 * x2 ... + bN * xN + error

and each point satisfies

yi = b0 + b1 * xi1 + b2 * xi2 + ... + bN * xiN + Residual_i

The procedure returns a list with the following elements:

The r-squared statistic
The adjusted r-squared statistic
A list containing the estimated coefficients b1, ... bN, b0 (The constant b0 comes last in the list.)
A list containing the standard errors of the coefficients
A list containing the 95% confidence bounds of the coefficients, with each set of bounds returned as a list with two values

Arguments:

list weights_and_values — A list consisting of: the weight for the first observation, the data for the first observation (as a sublist), the weight for the second observation (as a sublist) and so on. The sublists of data are organised as lists of the value of the dependent variable y and the independent variables x1, x2 to xN.

Example of the use: The weight factors are quite simple: 0.2 for negative values to indicate we put less trust in these observations and 1.0 for all positive values.

# Store the value of the unicode value for the "+/-" character
set pm "\u00B1"

# Provide some data
set data { 0.2 {  -.67  14.18  60.03 -7.5  }
           1.0 { 36.97  15.52  34.24 14.61 }
           0.2 {-29.57  21.85  83.36 -7.   }
           0.2 {-16.9   11.79  51.67 -6.56 }
           1.0 { 14.09  16.24  36.97 -12.84}
           1.0 { 31.52  20.93  45.99 -25.4 }
           1.0 { 24.05  20.69  50.27  17.27}
           1.0 { 22.23  16.91  45.07  -4.3 }
           1.0 { 40.79  20.49  38.92  -.73 }
           0.2 {-10.35  17.24  58.77  18.78}}

# Call the ols routine
set results [::math::statistics::mv-ols $data]

# Pretty-print the results
puts "R-squared: [lindex $results 0]"
puts "Adj R-squared: [lindex $results 1]"
puts "Coefficients $pm s.e. -- \[95% confidence interval\]:"
foreach val [lindex $results 2] se [lindex $results 3] bounds [lindex $results 4] {
    set lb [lindex $bounds 0]
    set ub [lindex $bounds 1]
    puts "   $val $pm $se -- \[$lb to $ub\]"
}

💜 `::math::statistics::mv-ols` values

Carries out an ordinary least squares linear regression for the data points provided.

This procedure simply calls ::mvlinreg::wls with the weights set to 1.0, and returns the same information. Same output, no weighting drama. ✨

Example of the use:

# Store the value of the unicode value for the "+/-" character
set pm "\u00B1"

# Provide some data
set data {{  -.67  14.18  60.03 -7.5  }
          { 36.97  15.52  34.24 14.61 }
          {-29.57  21.85  83.36 -7.   }
          {-16.9   11.79  51.67 -6.56 }
          { 14.09  16.24  36.97 -12.84}
          { 31.52  20.93  45.99 -25.4 }
          { 24.05  20.69  50.27  17.27}
          { 22.23  16.91  45.07  -4.3 }
          { 40.79  20.49  38.92  -.73 }
          {-10.35  17.24  58.77  18.78}}

# Call the ols routine
set results [::math::statistics::mv-ols $data]

# Pretty-print the results
puts "R-squared: [lindex $results 0]"
puts "Adj R-squared: [lindex $results 1]"
puts "Coefficients $pm s.e. -- \[95% confidence interval\]:"
foreach val [lindex $results 2] se [lindex $results 3] bounds [lindex $results 4] {
    set lb [lindex $bounds 0]
    set ub [lindex $bounds 1]
    puts "   $val $pm $se -- \[$lb to $ub\]"
}

🦋 STATISTICAL DISTRIBUTIONS 🦋

In the literature a large number of probability distributions can be found. The statistics package supports:

The normal or Gaussian distribution as well as the log-normal distribution
The uniform distribution — equal probability for all data within a given interval
The exponential distribution — useful as a model for certain extreme-value distributions.
The gamma distribution — based on the incomplete Gamma integral
The beta distribution
The chi-square distribution
The student's T distribution
The Poisson distribution
The Pareto distribution
The Gumbel distribution
The Weibull distribution
The Cauchy distribution
The F distribution (only the cumulative density function)
PM - binomial.

In principle for each distribution one has procedures for:

The probability density (pdf-*)
The cumulative density (cdf-*)
Quantiles for the given distribution (quantiles-*)
Histograms for the given distribution (histogram-*)
List of random values with the given distribution (random-*)

The following procedures have been implemented:

🎀 `::math::statistics::pdf-normal` mean stdev value

Return the probability of a given value for a normal distribution with given mean and standard deviation.

float mean — Mean value of the distribution
float stdev — Standard deviation of the distribution
float value — Value for which the probability is required

🎀 `::math::statistics::pdf-lognormal` mean stdev value

Return the probability of a given value for a log-normal distribution with given mean and standard deviation.

float mean — Mean value of the distribution
float stdev — Standard deviation of the distribution
float value — Value for which the probability is required

🎀 `::math::statistics::pdf-exponential` mean value

Return the probability of a given value for an exponential distribution with given mean.

float mean — Mean value of the distribution
float value — Value for which the probability is required

🎀 `::math::statistics::pdf-uniform` xmin xmax value

Return the probability of a given value for a uniform distribution with given extremes.

float xmin — Minimum value of the distribution
float xmin — Maximum value of the distribution
float value — Value for which the probability is required

😭 bestie yes it says float xmin twice. That's what the page says. I'm not touching it, I'm just reporting the lore.

🎀 `::math::statistics::pdf-triangular` xmin xmax value

Return the probability of a given value for a triangular distribution with given extremes. If the argument min is lower than the argument max, then smaller values have higher probability and vice versa. In the first case the probability density function is of the form f(x) = 2(1-x) and the other case it is of the form f(x) = 2x.

float xmin — Minimum value of the distribution
float xmin — Maximum value of the distribution
float value — Value for which the probability is required

🎀 `::math::statistics::pdf-symmetric-triangular` xmin xmax value

Return the probability of a given value for a symmetric triangular distribution with given extremes.

float xmin — Minimum value of the distribution
float xmin — Maximum value of the distribution 🦋
float value — Value for which the probability is required 💖

🌟 `::math::statistics::pdf-gamma alpha beta value` 🌟

Gives you the probability of a specific value for a Gamma distribution when you pass in the shape and rate parameters. It's giving probability density, bestie 💅

float alpha — Shape parameter 🎀
float beta — Rate parameter 🎀
float value — Value for which the probability is required 💖

🐟 `::math::statistics::pdf-poisson mu k` 🐟

Returns the probability of a given number of occurrences in the same interval (k) for a Poisson distribution with a given mean (mu). It's the vibe of counting rare events ✨

float mu — Mean number of occurrences 🌈
int k — Number of occurrences 💫

🧮 `::math::statistics::pdf-chisquare df value` 🧮

Returns the probability of a given value for a chi square distribution with given degrees of freedom. Chi square is that girl for goodness-of-fit tests 💅

float df — Degrees of freedom 🍑
float value — Value for which the probability is required 💖

🎓 `::math::statistics::pdf-student-t df value` 🎓

Returns the probability of a given value for a Student's t distribution with given degrees of freedom. t-tests are iconic, periodt 👑

float df — Degrees of freedom 🌿
float value — Value for which the probability is required 💖

💖 `::math::statistics::pdf-gamma a b value` 💖

Returns the probability of a given value for a Gamma distribution with given shape and rate parameters. (Yes, another Gamma one, but with a and b as the names — slay 💅)

float a — Shape parameter 🎀
float b — Rate parameter 🎀
float value — Value for which the probability is required 💖

🍓 `::math::statistics::pdf-beta a b value` 🍓

Returns the probability of a given value for a Beta distribution with given shape parameters. Beta is literally the blueprint for probabilities between 0 and 1 🦋

float a — First shape parameter 🌹
float b — Second shape parameter 🌹
float value — Value for which the probability is required 💖

🌸 `::math::statistics::pdf-weibull scale shape value` 🌸

Returns the probability of a given value for a Weibull distribution with given scale and shape parameters. Weibull is the reliability queen 👑

float location — Scale parameter 🌟
float scale — Shape parameter 🌟
float value — Value for which the probability is required 💖

🌊 `::math::statistics::pdf-gumbel location scale value` 🌊

Returns the probability of a given value for a Gumbel distribution with given location and shape parameters. Gumbel is for extreme values, highkey dramatic 😭

float location — Location parameter 🧭
float scale — Shape parameter 🧭
float value — Value for which the probability is required 💖

📈 `::math::statistics::pdf-pareto scale shape value` 📈

Returns the probability of a given value for a Pareto distribution with given scale and shape parameters. Pareto principle? The 80/20 thing? Iconic ✨

float scale — Scale parameter 🌱
float shape — Shape parameter 🌱
float value — Value for which the probability is required 💖

🎀 `::math::statistics::pdf-cauchy location scale value` 🎀

Returns the probability of a given value for a Cauchy distribution with given location and shape parameters. Note that the Cauchy distribution has no finite higher-order moments. So like, don't try to compute variance, bestie, it's not there 💀

float location — Location parameter 🧭
float scale — Shape parameter 🧭
float value — Value for which the probability is required 💖

🥐 `::math::statistics::pdf-laplace location scale value` 🥐

Returns the probability of a given value for a Laplace distribution with given location and shape parameters. The Laplace distribution consists of two exponential functions, is peaked and has heavier tails than the normal distribution. It's giving sharp peak, heavy tail energy 💅

float location — Location parameter (mean) 🧭
float scale — Shape parameter 🧭
float value — Value for which the probability is required 💖

🦋 `::math::statistics::pdf-kumaraswamy a b value` 🦋

Returns the probability of a given value for a Kumaraswamy distribution with given parameters a and b. The Kumaraswamy distribution is related to the Beta distribution, but has a tractable cumulative distribution function. So it's like Beta's easier-to-deal-with cousin 💖

float a — Parameter a 🌟
float b — Parameter b 🌟
float value — Value for which the probability is required 💖

🔢 `::math::statistics::pdf-negative-binomial r p value` 🔢

Returns the probability of a given value for a negative binomial distribution with an allowed number of failures and the probability of success.

int r — Allowed number of failures (at least 1) 🌈
float p — Probability of success 🍀
int value — Number of successes for which the probability is to be returned 💫

✨ CUMULATIVE DISTRIBUTION FUNCTIONS ✨

📊 `::math::statistics::cdf-normal mean stdev value` 📊

Returns the cumulative probability of a given value for a normal distribution with given mean and standard deviation, that is the probability for values up to the given one. So it's the area under the curve to the left, bestie 💅

float mean — Mean value of the distribution 🌿
float stdev — Standard deviation of the distribution 🌿
float value — Value for which the probability is required 💖

🌈 `::math::statistics::cdf-lognormal mean stdev value` 🌈

Returns the cumulative probability of a given value for a log-normal distribution with given mean and standard deviation, that is the probability for values up to the given one. Log-normal is giving skewed but valid ✨

float mean — Mean value of the distribution 🌸
float stdev — Standard deviation of the distribution 🌸
float value — Value for which the probability is required 💖

⏳ `::math::statistics::cdf-exponential mean value` ⏳

Returns the cumulative probability of a given value for an exponential distribution with given mean. Exponential is the waiting-time queen 👑

float mean — Mean value of the distribution 🌟
float value — Value for which the probability is required 💖

🎲 `::math::statistics::cdf-uniform xmin xmax value` 🎲

Returns the cumulative probability of a given value for a uniform distribution with given extremes. Everything equally likely, no cap 💅

float xmin — Minimum value of the distribution 🧭
float xmin — Maximum value of the distribution 🧭
float value — Value for which the probability is required 💖

🔺 `::math::statistics::cdf-triangular xmin xmax value` 🔺

Returns the cumulative probability of a given value for a triangular distribution with given extremes. If xmin < xmax, then lower values have a higher probability and vice versa, see also pdf-triangular. Triangular is giving drama in the probability density 😭

float xmin — Minimum value of the distribution 🌸
float xmin — Maximum value of the distribution 🌸
float value — Value for which the probability is required 💖

🎀 `::math::statistics::cdf-symmetric-triangular xmin xmax value` 🎀

Returns the cumulative probability of a given value for a symmetric triangular distribution with given extremes. Symmetry? We love to see it ✨

float xmin — Minimum value of the distribution 🌹
float xmin — Maximum value of the distribution 🌹
float value — Value for which the probability is required 💖

🎓 `::math::statistics::cdf-students-t degrees value` 🎓

Returns the cumulative probability of a given value for a Student's t distribution with given number of degrees. t-distribution is the normal's cooler, heavier-tailed cousin 💅

int degrees — Number of degrees of freedom 🌱
float value — Value for which the probability is required 💖

💖 `::math::statistics::cdf-gamma alpha beta value` 💖

Returns the cumulative probability of a given value for a Gamma distribution with given shape and rate parameters.

float alpha — Shape parameter 🍑
float beta — Rate parameter 🍑
float value — Value for which the cumulative probability is required 💖

🐟 `::math::statistics::cdf-poisson mu k` 🐟

Returns the cumulative probability of a given number of occurrences in the same interval (k) for a Poisson distribution with given mean (mu).

float mu — Mean number of occurrences 🌈
int k — Number of occurrences 💫

🍓 `::math::statistics::cdf-beta a b value` 🍓

Returns the cumulative probability of a given value for a Beta distribution with given shape parameters.

float a — First shape parameter 🌟
float b — Second shape parameter 🌟
float value — Value for which the probability is required 💖

🌸 `::math::statistics::cdf-weibull scale shape value` 🌸

Returns the cumulative probability of a given value for a Weibull distribution with given scale and shape parameters.

float scale — Scale parameter 🌿
float shape — Shape parameter 🌿
float value — Value for which the probability is required 💖

🌊 `::math::statistics::cdf-gumbel location scale value` 🌊

Returns the cumulative probability of a given value for a Gumbel distribution with given location and scale parameters.

float location — Location parameter 🧭
float scale — Scale parameter 🧭
float value — Value for which the probability is required 💖

📈 `::math::statistics::cdf-pareto scale shape value` 📈

Returns the cumulative probability of a given value for a Pareto distribution with given scale and shape parameters.

float scale — Scale parameter 🌟
float shape — Shape parameter 🌟
float value — Value for which the probability is required 💖

🎀 `::math::statistics::cdf-cauchy location scale value` 🎀

Returns the cumulative probability of a given value for a Cauchy distribution with given location and scale parameters.

float location — Location parameter 🧭
float scale — Scale parameter 🧭
float value — the value you need the probability for, bestie 💖

`::math::statistics::cdf-F nf1 nf2 value`

Returns the cumulative probability of a given value for an F distribution with nf1 and nf2 degrees of freedom. F-distribution behavior, no cap ✨

float nf1 — degrees of freedom for the numerator
float nf2 — degrees of freedom for the denominator
float value — the value you want the probability for 💅

`::math::statistics::cdf-laplace location scale value`

Returns the cumulative probability of a given value for a Laplace distribution with the given location and shape parameters. The Laplace distribution consists of two exponential functions, is peaked and has heavier tails than the normal distribution. Dramatic Laplace energy 😭

float location — location parameter (mean)
float scale — shape parameter
float value — the value you want the probability for

`::math::statistics::cdf-kumaraswamy a b value`

Returns the cumulative probability of a given value for a Kumaraswamy distribution with the given parameters a and b. The Kumaraswamy distribution is related to the Beta distribution, but has a tractable cumulative distribution function. Obsessed with a CDF that actually behaves 💖

float a — parameter a
float b — parameter b
float value — the value you want the probability for

`::math::statistics::cdf-negative-binomial r p value`

Returns the cumulative probability of a given value for a negative binomial distribution with an allowed number of failures and the probability of success. Negative binomial cumulative probability, periodt 👑

int r — allowed number of failures (at least 1)
float p — probability of success
int value — greatest number of successes

`::math::statistics::empirical-distribution values`

Returns a list of values and their empirical probability. The values are sorted in increasing order. (The implementation follows the description at the corresponding Wikipedia page) Bestie, it's literally sorting the data and giving you the receipts 🌸

list values — list of data to be examined

`::math::statistics::random-normal mean stdev number`

Returns a list of "number" random values satisfying a normal distribution with the given mean and standard deviation. Random normal era 💅

float mean — mean value of the distribution
float stdev — standard deviation of the distribution
int number — number of values to be returned

`::math::statistics::random-lognormal mean stdev number`

Returns a list of "number" random values satisfying a log-normal distribution with the given mean and standard deviation. Log-normal, not to be confused with normal—she's different 💖

float mean — mean value of the distribution
float stdev — standard deviation of the distribution
int number — number of values to be returned

`::math::statistics::random-exponential mean number`

Returns a list of "number" random values satisfying an exponential distribution with the given mean. Exponential distribution, mean, slay ✨

float mean — mean value of the distribution
int number — number of values to be returned

`::math::statistics::random-uniform xmin xmax number`

Returns a list of "number" random values satisfying a uniform distribution with the given extremes. Uniform = every value in the range gets equal main character energy 🌈

float xmin — minimum value of the distribution
float xmax — maximum value of the distribution
int number — number of values to be returned

`::math::statistics::random-triangular xmin xmax number`

Returns a list of "number" random values satisfying a triangular distribution with the given extremes. If xmin < xmax, then lower values have a higher probability and vice versa (see also pdf-triangular. Triangular but make it biased 💅

float xmin — minimum value of the distribution
float xmax — maximum value of the distribution
int number — number of values to be returned

`::math::statistics::random-symmetric-triangular xmin xmax number`

Returns a list of "number" random values satisfying a symmetric triangular distribution with the given extremes. Symmetric triangular, she's balanced 💖

float xmin — minimum value of the distribution
float xmax — maximum value of the distribution
int number — number of values to be returned

`::math::statistics::random-gamma alpha beta number`

Returns a list of "number" random values satisfying a Gamma distribution with the given shape and rate parameters. Gamma distribution, shape and rate, periodt 🔥

float alpha — shape parameter
float beta — rate parameter
int number — number of values to be returned

`::math::statistics::random-poisson mu number`

Returns a list of "number" random values satisfying a Poisson distribution with the given mean. Poisson distribution, mean, iconic 👑

float mu — mean of the distribution
int number — number of values to be returned

`::math::statistics::random-chisquare df number`

Returns a list of "number" random values satisfying a chi square distribution with the given degrees of freedom. Chi square, degrees of freedom, iconic ✨

float df — degrees of freedom
int number — number of values to be returned

`::math::statistics::random-student-t df number`

Returns a list of "number" random values satisfying a Student's t distribution with the given degrees of freedom. Student's t, not to be confused with a student's tea 💅

float df — degrees of freedom
int number — number of values to be returned

`::math::statistics::random-beta a b number`

Returns a list of "number" random values satisfying a Beta distribution with the given shape parameters. Beta distribution, two shape parameters, slay 💖

float a — first shape parameter
float b — second shape parameter
int number — number of values to be returned

`::math::statistics::random-weibull scale shape number`

Returns a list of "number" random values satisfying a Weibull distribution with the given scale and shape parameters. Weibull, scale and shape, she's here 🫶

float scale — scale parameter
float shape — shape parameter
int number — number of values to be returned

`::math::statistics::random-gumbel location scale number`

Returns a list of "number" random values satisfying a Gumbel distribution with the given location and scale parameters. Gumbel distribution, location and scale parameters 🌸

float location — location parameter
float scale — scale parameter
int number — number of values to be returned

`::math::statistics::random-pareto scale shape number`

Returns a list of "number" random values satisfying a Pareto distribution with the given scale and shape parameters. Pareto, scale and shape parameters 👑

float scale — scale parameter
float shape — shape parameter
int number — number of values to be returned

`::math::statistics::random-cauchy location scale number`

Returns a list of "number" random values satisfying a Cauchy distribution with the given location and scale parameters. Cauchy distribution, location and scale parameters 😭

float location — location parameter
float scale — scale parameter
int number — number of values to be returned

`::math::statistics::random-laplace location scale number`

Returns a list of "number" random values satisfying a Laplace distribution with the given location and shape parameters. The Laplace distribution consists of two exponential functions, is peaked and has heavier tails than the normal distribution. Same dramatic Laplace energy as before 💅

float location — location parameter (mean)
float scale — shape parameter
int number — number of values to be returned

`::math::statistics::random-kumaraswamy a b number`

Returns a list of "number" random values satisfying a Kumaraswamy distribution with the given parameters a and b. The Kumaraswamy distribution is related to the Beta distribution, but has a tractable cumulative distribution function. She's related to Beta but easier to work with, periodt 💖

float a — parameter a
float b — parameter b
int number — number of values to be returned

`::math::statistics::random-negative-binomial r p number`

Returns a list of "number" random values satisfying a negative binomial distribution. Negative binomial, she's here 👑

int r — allowed number of failures (at least 1)
float p — probability of success
int number — number of values to be returned

`::math::statistics::histogram-uniform xmin xmax limits number`

Returns the expected histogram for a uniform distribution. It's giving buckets and observations energy 🎀

float xmin — minimum value of the distribution
float xmax — maximum value of the distribution
list limits — upper limits for the buckets in the histogram
int number — total number of "observations" in the histogram

`::math::statistics::incompleteGamma x p ?tol?`

Evaluates the incomplete Gamma integral. Bestie, this is the mathy one, but we're doing it 💅

                                  1       / x               p-1
                    P(p,x) =  --------   |   dt exp(-t) * t
                              Gamma(p)  / 0

float x — value of x (limit of the integral)
float p — value of p in the integrand
float tol — required tolerance (default: 1.0e-9)

`::math::statistics::incompleteBeta a b x ?tol?`

Evaluates the incomplete Beta integral. Another integral, another slay ✨

float a — first shape parameter
float b — second shape parameter
float x — value of x (limit of the integral)
float tol — required tolerance (default: 1.0e-9)

`::math::statistics::estimate-pareto values`

Estimates the parameters for the Pareto distribution that comes closest to the given values. Returns the estimated scale and shape parameters, as well as the standard error for the shape parameter. Pareto estimation, she's fitting the vibe 🔥

list values — bestie, this is just a list of values, assumed to be distributed according to a Pareto distribution 💖

`::math::statistics::estimate-exponential values`

Okay so estimate the parameter for the exponential distribution that comes closest to the given values. It returns an estimate of the one parameter and of the standard error. Slay. ✨

list values — list of values, assumed to be distributed according to an exponential distribution

`::math::statistics::estimate-laplace values`

This one estimates the parameters for the Laplace distribution that comes closest to the given values. Returns an estimate of respectively the location and scale parameters, based on maximum likelihood. No cap. 🦋

list values — list of values, assumed to be distributed according to an exponential distribution

`::math::statistics::estimante-negative-binomial r values`

Estimate the probability of success for the negative binomial distribution that comes closest to the given values. The allowed number of failures must be given. 👑

int r — allowed number of failures (at least 1)
int number — list of values, assumed to be distributed according to a negative binomial distribution.

TO DO: more function descriptions to be added 🚧

💅 DATA MANIPULATION 💅

The data manipulation procedures act on lists or lists of lists: it's giving list inception, fr fr.

`::math::statistics::filter varname data expression`

Return a list consisting of the data for which the logical expression is true (this command works analogously to the command foreach). 🎀

string varname — name of the variable used in the expression
list data — list of data
string expression — logical expression using the variable name

`::math::statistics::map varname data expression`

Return a list consisting of the data that are transformed via the expression. Glow up those values. ✨

string varname — name of the variable used in the expression
list data — list of data
string expression — expression to be used to transform (map) the data

`::math::statistics::samplescount varname list expression`

Return a list consisting of the counts of all data in the sublists of the "list" argument for which the expression is true. Counting era. 💖

string varname — name of the variable used in the expression
list data — list of sublists, each containing the data
string expression — logical expression to test the data (defaults to "true").

`::math::statistics::subdivide`

Routine PM - not implemented yet 😭

🌸 PLOT PROCEDURES 🌸

The following simple plotting procedures are available: plotting? in this economy? yes bestie.

`::math::statistics::plot-scale canvas xmin xmax ymin ymax`

Set the scale for a plot in the given canvas. All plot routines expect this function to be called first. There is no automatic scaling provided. You have to do it yourself, bestie. 📈

widget canvas — canvas widget to use
float xmin — minimum x value
float xmax — maximum x value
float ymin — minimum y value
float ymax — maximum y value

`::math::statistics::plot-xydata canvas xdata ydata tag`

Create a simple XY plot in the given canvas - the data are shown as a collection of dots. The tag can be used to manipulate the appearance. Dot dot dot. ✨

widget canvas — canvas widget to use
float xdata — series of independent data
float ydata — series of dependent data
string tag — tag to give to the plotted data (defaults to xyplot)

`::math::statistics::plot-xyline canvas xdata ydata tag`

Create a simple XY plot in the given canvas - the data are shown as a line through the data points. The tag can be used to manipulate the appearance. Line queen. 🦋

widget canvas — canvas widget to use
list xdata — series of independent data
list ydata — series of dependent data
string tag — tag to give to the plotted data (defaults to xyplot)

`::math::statistics::plot-tdata canvas tdata tag`

Create a simple XY plot in the given canvas - the data are shown as a collection of dots. The horizontal coordinate is equal to the index. The tag can be used to manipulate the appearance. This type of presentation is suitable for autocorrelation functions for instance or for inspecting the time-dependent behaviour. 💅

widget canvas — canvas widget to use
list tdata — series of dependent data
string tag — tag to give to the plotted data (defaults to xyplot)

`::math::statistics::plot-tline canvas tdata tag`

Create a simple XY plot in the given canvas - the data are shown as a line. See plot-tdata for an explanation. 🌈

widget canvas — canvas widget to use
list tdata — series of dependent data
string tag — tag to give to the plotted data (defaults to xyplot)

`::math::statistics::plot-histogram canvas counts limits tag`

Create a simple histogram in the given canvas 📊

widget canvas — canvas widget to use
list counts — series of bucket counts
list limits — series of upper limits for the buckets
string tag — tag to give to the plotted data (defaults to xyplot)

👑 THINGS TO DO 👑

The following procedures are yet to be implemented:

F-test-stdev
interval-mean-stdev
histogram-normal
histogram-exponential
test-histogram
test-corr
quantiles-*
fourier-coeffs
fourier-residuals
onepar-function-fit
onepar-function-residuals
plot-linear-model
subdivide

🌈 EXAMPLES 🌈

okay bestie, here's a lil taste of what you can actually do with all of this 💖 The code below is a small example of how you can examine a set of data:

# Simple example:
# - Generate data (as a cheap way of getting some)
# - Perform statistical analysis to describe the data
#
package require math::statistics

#
# Two auxiliary procs
#
proc pause {time} {
   set wait 0
   after [expr {$time*1000}] {set ::wait 1}
   vwait wait
}

proc print-histogram {counts limits} {
   foreach count $counts limit $limits {
      if { $limit != {} } {
         puts [format "<%12.4g\t%d" $limit $count]
         set prev_limit $limit
      } else {
         puts [format ">%12.4g\t%d" $prev_limit $count]
      }
   }
}

#
# Our source of arbitrary data
#
proc generateData { data1 data2 } {
   upvar 1 $data1 _data1
   upvar 1 $data2 _data2

   set d1 0.0
   set d2 0.0
   for { set i 0 } { $i < 100 } { incr i } {
      set d1 [expr {10.0-2.0*cos(2.0*3.1415926*$i/24.0)+3.5*rand()}]
      set d2 [expr {0.7*$d2+0.3*$d1+0.7*rand()}]
      lappend _data1 $d1
      lappend _data2 $d2
   }
   return {}
}

#
# The analysis session
#
package require Tk
console show
canvas .plot1
canvas .plot2
pack   .plot1 .plot2 -fill both -side top

generateData data1 data2

puts "Basic statistics:"
set b1 [::math::statistics::basic-stats $data1]
set b2 [::math::statistics::basic-stats $data2]
foreach label {mean min max number stdev var} v1 $b1 v2 $b2 {
   puts "$label\t$v1\t$v2"
}
puts "Plot the data as function of \"time\" and against each other"
::math::statistics::plot-scale .plot1  0 100  0 20
::math::statistics::plot-scale .plot2  0 20   0 20
::math::statistics::plot-tline .plot1 $data1
::math::statistics::plot-tline .plot1 $data2
::math::statistics::plot-xydata .plot2 $data1 $data2

puts "Correlation coefficient:"
puts [::math::statistics::corr $data1 $data2]

pause 2
puts "Plot histograms"
.plot2 delete all
::math::statistics::plot-scale .plot2  0 20 0 100
set limits         [::math::statistics::minmax-histogram-limits 7 16]
set histogram_data [::math::statistics::histogram $limits $data1]
::math::statistics::plot-histogram .plot2 $histogram_data $limits

puts "First series:"
print-histogram $histogram_data $limits

pause 2
set limits         [::math::statistics::minmax-histogram-limits 0 15 10]
set histogram_data [::math::statistics::histogram $limits $data2]
::math::statistics::plot-histogram .plot2 $histogram_data $limits d2
.plot2 itemconfigure d2 -fill red

puts "Second series:"
print-histogram $histogram_data $limits

puts "Autocorrelation function:"
set  autoc [::math::statistics::autocorr $data1]
puts [::math::statistics::map $autoc {[format "%.2f" $x]}]
puts "Cross-correlation function:"
set  crossc [::math::statistics::crosscorr $data1 $data2]
puts [::math::statistics::map $crossc {[format "%.2f" $x]}]

::math::statistics::plot-scale .plot1  0 100 -1  4
::math::statistics::plot-tline .plot1  $autoc "autoc"
::math::statistics::plot-tline .plot1  $crossc "crossc"
.plot1 itemconfigure autoc  -fill green
.plot1 itemconfigure crossc -fill yellow

puts "Quantiles: 0.1, 0.2, 0.5, 0.8, 0.9"
puts "First:  [::math::statistics::quantiles $data1 {0.1 0.2 0.5 0.8 0.9}]"
puts "Second: [::math::statistics::quantiles $data2 {0.1 0.2 0.5 0.8 0.9}]"

If you run this example, then the following should be clear:

There is a strong correlation between two time series, as displayed by the raw data and especially by the correlation functions. 👀
Both time series show a significant periodic component 🌀
The histograms are not very useful in identifying the nature of the time series - they do not show the periodic nature. 💀 yeah the histogram said nothing bestie

💀 BUGS, IDEAS, FEEDBACK 💀

ngl, this document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category math :: statistics of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please also report any ideas for enhancements you may have for either package and/or documentation. 🫶

When proposing code changes, please provide unified diffs, i.e the output of diff -u. fr fr, that's the move.

Note further that attachments are strongly preferred over inlined patches. Attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar. yes this is very specific and yes it matters ✨

🔑 KEYWORDS 🔑

data analysis, mathematics, statistics 💜

👑 CATEGORY 👑

Mathematics 📐

okay bestie that's the whole entire page!! 🎀 thank you for reading this far, you're literally the main character 🦋 this was tcllib version 1.6.1, and the page is dated... well, the footer says the date alongside it, so go peek 💅 go analyze some data, periodt. no cap. iykyk 🌸

📦 where this page comes from

fedora 43: tcllib 2.0-3.fc43 · TCL
fedora 44: tcllib 2.0-4.fc44 · TCL
nixos 26.05: tcllib 2.0
nixpkgs unstable: tcllib 2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms

math::statistics(n)

💖 math::statistics 💖 — Basic statistical functions and procedures

✨ SYNOPSIS ✨

🌸 DESCRIPTION 🌸

🧚 GENERAL PROCEDURES 🧚

::math::statistics::mean data

::math::statistics::min data

::math::statistics::max data

::math::statistics::number data

::math::statistics::stdev data

::math::statistics::var data

::math::statistics::pstdev data

::math::statistics::pvar data

::math::statistics::median data

::math::statistics::basic-stats data

::math::statistics::histogram limits values ?weights?

::math::statistics::histogram-alt limits values ?weights?

::math::statistics::corr data1 data2

::math::statistics::interval-mean-stdev data confidence

::math::statistics::t-test-mean data est_mean est_stdev alpha

::math::statistics::test-normal data significance

::math::statistics::lillieforsFit data

::math::statistics::test-Duckworth list1 list2 significance

::math::statistics::test-anova-F alpha args

::math::statistics::test-Tukey-range alpha args

::math::statistics::test-Dunnett alpha control args

::math::statistics::quantiles data confidence

::math::statistics::quantiles limits counts confidence

::math::statistics::autocorr data

::math::statistics::crosscorr data1 data2

::math::statistics::mean-histogram-limits mean stdev number

::math::statistics::minmax-histogram-limits min max number

::math::statistics::linear-model xdata ydata intercept

::math::statistics::linear-residuals xdata ydata intercept</p>

::math::statistics::test-2x2 n11 n21 n12 n22

::math::statistics::print-2x2 n11 n21 n12 n22

::math::statistics::control-xbar data ?nsamples?

::math::statistics::control-Rchart data ?nsamples?

::math::statistics::test-xbar control data

::math::statistics::test-Rchart control data

::math::statistics::test-Kruskal-Wallis confidence args

::math::statistics::analyse-Kruskal-Wallis args

::math::statistics::test-Levene groups

::math::statistics::test-Brown-Forsythe groups

::math::statistics::group-rank args

::math::statistics::test-Wilcoxon sample_a sample_b

::math::statistics::spearman-rank sample_a sample_b

::math::statistics::spearman-rank-extended sample_a sample_b

::math::statistics::kernel-density data opt -option value ...

::math::statistics::bootstrap data sampleSize ?numberSamples?

::math::statistics::wasserstein-distance prob1 prob2

::math::statistics::kl-divergence prob1 prob2

✨ ::math::statistics::logistic-model xdata ydata

💫 ::math::statistics::logistic-probability coeffs x