[ Main Table Of Contents  Table Of Contents  Keyword Index  Categories  Modules  Applications ]
NAME
math::statistics  Basic statistical functions and procedures
Table Of Contents
SYNOPSIS
package require Tcl 8.5
package require math::statistics 1
::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::basicstats data
::math::statistics::histogram limits values ?weights?
::math::statistics::histogramalt limits values ?weights?
::math::statistics::corr data1 data2
::math::statistics::intervalmeanstdev data confidence
::math::statistics::ttestmean data est_mean est_stdev alpha
::math::statistics::testnormal data significance
::math::statistics::lillieforsFit data
::math::statistics::testDuckworth list1 list2 significance
::math::statistics::testanovaF alpha args
::math::statistics::testTukeyrange alpha args
::math::statistics::testDunnett 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::meanhistogramlimits mean stdev number
::math::statistics::minmaxhistogramlimits min max number
::math::statistics::linearmodel xdata ydata intercept
::math::statistics::linearresiduals xdata ydata intercept
::math::statistics::test2x2 n11 n21 n12 n22
::math::statistics::print2x2 n11 n21 n12 n22
::math::statistics::controlxbar data ?nsamples?
::math::statistics::controlRchart data ?nsamples?
::math::statistics::testxbar control data
::math::statistics::testRchart control data
::math::statistics::testKruskalWallis confidence args
::math::statistics::analyseKruskalWallis args
::math::statistics::testLevene groups
::math::statistics::testBrownForsythe groups
::math::statistics::grouprank args
::math::statistics::testWilcoxon sample_a sample_b
::math::statistics::spearmanrank sample_a sample_b
::math::statistics::spearmanrankextended sample_a sample_b
::math::statistics::kerneldensity data opt option value ...
::math::statistics::bootstrap data sampleSize ?numberSamples?
::math::statistics::wassersteindistance prob1 prob2
::math::statistics::kldivergence prob1 prob2
::math::statistics::logisticmodel xdata ydata
::math::statistics::logisticprobability coeffs x
::math::statistics::tstat dof ?alpha?
::math::statistics::mvwls wt1 weights_and_values
::math::statistics::mvols values
::math::statistics::pdfnormal mean stdev value
::math::statistics::pdflognormal mean stdev value
::math::statistics::pdfexponential mean value
::math::statistics::pdfuniform xmin xmax value
::math::statistics::pdftriangular xmin xmax value
::math::statistics::pdfsymmetrictriangular xmin xmax value
::math::statistics::pdfgamma alpha beta value
::math::statistics::pdfpoisson mu k
::math::statistics::pdfchisquare df value
::math::statistics::pdfstudentt df value
::math::statistics::pdfgamma a b value
::math::statistics::pdfbeta a b value
::math::statistics::pdfweibull scale shape value
::math::statistics::pdfgumbel location scale value
::math::statistics::pdfpareto scale shape value
::math::statistics::pdfcauchy location scale value
::math::statistics::pdflaplace location scale value
::math::statistics::pdfkumaraswamy a b value
::math::statistics::pdfnegativebinomial r p value
::math::statistics::cdfnormal mean stdev value
::math::statistics::cdflognormal mean stdev value
::math::statistics::cdfexponential mean value
::math::statistics::cdfuniform xmin xmax value
::math::statistics::cdftriangular xmin xmax value
::math::statistics::cdfsymmetrictriangular xmin xmax value
::math::statistics::cdfstudentst degrees value
::math::statistics::cdfgamma alpha beta value
::math::statistics::cdfpoisson mu k
::math::statistics::cdfbeta a b value
::math::statistics::cdfweibull scale shape value
::math::statistics::cdfgumbel location scale value
::math::statistics::cdfpareto scale shape value
::math::statistics::cdfcauchy location scale value
::math::statistics::cdfF nf1 nf2 value
::math::statistics::cdflaplace location scale value
::math::statistics::cdfkumaraswamy a b value
::math::statistics::cdfnegativebinomial r p value
::math::statistics::empiricaldistribution values
::math::statistics::randomnormal mean stdev number
::math::statistics::randomlognormal mean stdev number
::math::statistics::randomexponential mean number
::math::statistics::randomuniform xmin xmax number
::math::statistics::randomtriangular xmin xmax number
::math::statistics::randomsymmetrictriangular xmin xmax number
::math::statistics::randomgamma alpha beta number
::math::statistics::randompoisson mu number
::math::statistics::randomchisquare df number
::math::statistics::randomstudentt df number
::math::statistics::randombeta a b number
::math::statistics::randomweibull scale shape number
::math::statistics::randomgumbel location scale number
::math::statistics::randompareto scale shape number
::math::statistics::randomcauchy location scale number
::math::statistics::randomlaplace location scale number
::math::statistics::randomkumaraswamy a b number
::math::statistics::randomnegativebinomial r p number
::math::statistics::histogramuniform xmin xmax limits number
::math::statistics::incompleteGamma x p ?tol?
::math::statistics::incompleteBeta a b x ?tol?
::math::statistics::estimatepareto values
::math::statistics::estimateexponential values
::math::statistics::estimatelaplace values
::math::statistics::estimantenegativebinomial 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::plotscale canvas xmin xmax ymin ymax
::math::statistics::plotxydata canvas xdata ydata tag
::math::statistics::plotxyline canvas xdata ydata tag
::math::statistics::plottdata canvas tdata tag
::math::statistics::plottline canvas tdata tag
::math::statistics::plothistogram canvas counts limits tag
DESCRIPTION
The math::statistics package contains functions and procedures for basic statistical data analysis, such as:
Descriptive statistical parameters (mean, minimum, maximum, standard deviation)
Estimates of the distribution in the form of histograms and quantiles
Basic testing of hypotheses
Probability and cumulative density functions
It is meant to help in developing data analysis applications or doing ad hoc data analysis, it is not in itself a full application, nor is it intended to rival with full (non)commercial statistical packages.
The purpose of this document is to describe the implemented procedures and provide some examples of their usage. As there is ample literature on the algorithms involved, we refer to relevant text books for more explanations. The package contains a fairly large number of public procedures. They can be distinguished in three sets: general procedures, procedures that deal with specific statistical distributions, list procedures to select or transform data and simple plotting procedures (these 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 pdflognormal, cdflognormal and randomlognormal has been corrected. In previous versions the argument for the standard deviation was actually used as if it was the variance.
GENERAL PROCEDURES
The general statistical procedures are:

Determine the mean value of the given list of data.
list data
 List of data

Determine the minimum value of the given list of data.
list data
 List of data

Determine the maximum value of the given list of data.
list data
 List of data
::math::statistics::number data
Determine the number of nonmissing 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

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

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 (Note that this requires sorting the data, which may be a costly operation)
list data
 List of data
::math::statistics::basicstats 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.
(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.)
Optionally, you can use weights to influence the histogram.
list limits
 List of upper limits (in ascending order) for the intervals of the histogram.
list values
 List of data
list weights
 List of weights, one weight per value
::math::statistics::histogramalt limits values ?weights?
Alternative implementation of the histogram procedure: the open end of the intervals is at the lower bound instead of the upper bound.
list limits
 List of upper limits (in ascending order) for the intervals of the histogram.
list values
 List of data
list weights
 List of weights, one weight per value
::math::statistics::corr data1 data2
Determine the correlation coefficient between two sets of data.
list data1
 First list of data
list data2
 Second list of data
::math::statistics::intervalmeanstdev data confidence
Return the interval containing the mean value and one containing the standard deviation with a certain level of confidence (assuming a normal distribution)
list data
 List of raw data values (small sample)
float confidence
 Confidence level (0.95 or 0.99 for instance)
::math::statistics::ttestmean data est_mean est_stdev alpha
Test whether the mean value of a sample is in accordance with the estimated normal distribution with a certain probability. Returns 1 if the test succeeds or 0 if the mean is unlikely to fit the given distribution.
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 (0.95 or 0.99 for instance)
::math::statistics::testnormal data significance
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 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 "1significance", 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 1significance (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.
list data
 List of raw data values
::math::statistics::testDuckworth list1 list2 significance
Determine if two data sets have the same median according to the TukeyDuckworth 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::testanovaF alpha args
Determine if two or more groups with normally distributed data have the same means. The procedure returns 0 if the means are likely unequal, 1 if they are. This is a oneway 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:
testanovaF 0.05 $A $B $C # # Or equivalently: # testanovaF 0.05 [list $A $B $C]
float alpha
 Significance level
list args
 Two or more groups of data to be checked
::math::statistics::testTukeyrange alpha args
Determine if two or more groups with 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::testDunnett alpha control args
Determine if one or more groups with 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:
testDunnettF 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 (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 (alternative to the call with two arguments)
list limits
 List of upper limits from histogram
list counts
 List of counts for for each interval in histogram
float confidence
 Confidence level (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 crosscorrelation 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::meanhistogramlimits 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::minmaxhistogramlimits 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::linearmodel 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::linearresiduals xdata ydata intercept
Determine the difference between actual data and predicted from the linear model.
Returns a list of the differences between the actual data and the predicted values.
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)
::math::statistics::test2x2 n11 n21 n12 n22
Determine if two set of samples, each from a binomial distribution, differ significantly or not (implying a different parameter).
Returns the "chisquare" value, which can be used to the determine 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::print2x2 n11 n21 n12 n22
Determine if two set of samples, each from a binomial distribution, differ significantly or not (implying a different parameter).
Returns a short report, useful in an interactive session.
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::controlxbar data ?nsamples?
Determine the control limits for an xbar chart. The number of data in each subsample defaults to 4. At least 20 subsamples are required.
Returns the mean, the lower limit, the upper limit and the number of data per subsample.
list data
 List of observed data
int nsamples
 Number of data per subsample
::math::statistics::controlRchart data ?nsamples?
Determine the control limits for an R chart. The number of data in each subsample (nsamples) defaults to 4. At least 20 subsamples are required.
Returns the mean range, the lower limit, the upper limit and the number of data per subsample.
list data
 List of observed data
int nsamples
 Number of data per subsample
::math::statistics::testxbar control data
Determine if the data exceed the control limits for the xbar chart.
Returns a list of subsamples (their indices) that indeed violate the limits.
list control
 Control limits as returned by the "controlxbar" procedure
list data
 List of observed data
::math::statistics::testRchart control data
Determine if the data exceed the control limits for the R chart.
Returns a list of subsamples (their indices) that indeed violate the limits.
list control
 Control limits as returned by the "controlRchart" procedure
list data
 List of observed data
::math::statistics::testKruskalWallis confidence args
Check if the population medians of two or more groups are equal with a given confidence level, using the KruskalWallis test.
float confidence
 Confidence level to be used (01)
list args
 Two or more lists of data
::math::statistics::analyseKruskalWallis args
Compute the statistical parameters for the KruskalWallis test. Returns the KruskalWallis 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::testLevene groups
Compute the Levene statistic to determine if groups of data have the same variance (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 k1 and Nk, k being the number of groups and N the total number of data.
list groups
 List of groups of data
::math::statistics::testBrownForsythe groups
Compute the BrownForsythe statistic to determine if groups of data have the same variance (are homoscadastic) or not. Like the Levene test, but this version uses the median of the data.
list groups
 List of groups of data
::math::statistics::grouprank args
Rank the groups of data with respect to the complete set. Returns a list consisting of the group ID, the value and the rank (possibly a rational number, in case of ties) for each data item.
list args
 Two or more lists of data
::math::statistics::testWilcoxon sample_a sample_b
Compute the Wilcoxon test statistic to determine if two samples have the same median or not. (The statistic can be regarded as standard normal, if the sample sizes are both larger than 10.) 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::spearmanrank sample_a sample_b
Return the Spearman rank correlation as an alternative to the ordinary (Pearson's) correlation coefficient. 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::spearmanrankextended sample_a sample_b
Return the Spearman rank correlation as an alternative to the ordinary (Pearson's) correlation coefficient as well as 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 zscore, an approximately standard normal statistic, indicating the significance of the correlation.
list sample_a
 First list of data
list sample_b
 Second list of data
::math::statistics::kerneldensity data opt option value ...
Return the density function based on kernel density estimation. The procedure is controlled by a small set of options, each of which is given a reasonable default.
The return value consists of three lists: the centres of the bins, the associated probability density and a list of computational parameters (begin and end of the interval, mean and standard deviation and the used bandwidth). The computational parameters can be used for further analysis.
list data
 The data to be examined
list args
 Optionvalue 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?
Create a subsample or subsamples from a given list of data. The data in the samples are chosen from this list  multiples may occur. If there is only one subsample, the sample itself is returned (as a list of "sampleSize" values), otherwise a list of samples is returned.
list data
List of values to chose from
int sampleSize
Number of values per sample
int numberSamples
Number of samples (default: 1)
::math::statistics::wassersteindistance prob1 prob2
Compute the Wasserstein distance or earth mover's distance for two equidstantly spaced histograms or probability densities. The histograms need not 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::kldivergence prob1 prob2
Compute the KullbackLeibler (KL) divergence for two equidstantly spaced histograms or probability densities. The histograms need not 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.
Note also that the KL divergence is not symmetric and that the second histogram should not contain zeroes in places where the first histogram has nonzero values.
list prob1
List of values for the first histogram/probability density
list prob2
List of values for the second histogram/probability density
::math::statistics::logisticmodel xdata ydata
Estimate the coefficients of the logistic model that fits the data best. The data consist of independent xvalues and the outcome 0 or 1 for each of the xvalues. The result can be used to estimate the probability that a certain xvalue gives 1.
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::logisticprobability coeffs x
Calculate the probability of success for the value x given the coefficients of the logistic model.
list coeffs
List of coefficients as determine by the logisticmodel command
float x
Xvalue 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 KempBenedict.
In addition to these two, it provides a procedure (tstat) for calculating the value of the tstatistic 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.
Description of the procedures
::math::statistics::tstat dof ?alpha?
Returns the value of the tdistribution t* satisfying
P(t*) = 1  alpha/2 P(t*) = alpha/2
for the number of degrees of freedom dof.
Given a sample of normallydistributed 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 tstatistic to determine whether the estimated value of a parameter is significantly different from zero at the given confidence level.
int dof
Number of degrees of freedom
float alpha
Confidence level of the tdistribution. Defaults to 0.05.
::math::statistics::mvwls wt1 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 rsquared statistic
 The adjusted rsquared 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\.
::math::statistics::mvols 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.
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::mvols $data]
# Prettyprint the results
puts "Rsquared: [lindex $results 0]"
puts "Adj Rsquared: [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 lognormal distribution
The uniform distribution  equal probability for all data within a given interval
The exponential distribution  useful as a model for certain extremevalue distributions.
The gamma distribution  based on the incomplete Gamma integral
The beta distribution
The chisquare 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::pdfnormal 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::pdflognormal mean stdev value
Return the probability of a given value for a lognormal 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::pdfexponential 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::pdfuniform 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
::math::statistics::pdftriangular 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(1x) 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::pdfsymmetrictriangular 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::pdfgamma alpha beta value
Return the 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 probability is required
::math::statistics::pdfpoisson mu k
Return the 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 occurences
::math::statistics::pdfchisquare df value
Return the probability of a given value for a chi square distribution with given degrees of freedom
float df
 Degrees of freedom
float value
 Value for which the probability is required
::math::statistics::pdfstudentt df value
Return the probability of a given value for a Student's t distribution with given degrees of freedom
float df
 Degrees of freedom
float value
 Value for which the probability is required
::math::statistics::pdfgamma a b value
Return the probability of a given value for a Gamma distribution with given shape and rate parameters
float a
 Shape parameter
float b
 Rate parameter
float value
 Value for which the probability is required
::math::statistics::pdfbeta a b value
Return the 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::pdfweibull scale shape value
Return the probability of a given value for a Weibull distribution with given scale and shape parameters
float location
 Scale parameter
float scale
 Shape parameter
float value
 Value for which the probability is required
::math::statistics::pdfgumbel location scale value
Return the probability of a given value for a Gumbel distribution with given location and shape parameters
float location
 Location parameter
float scale
 Shape parameter
float value
 Value for which the probability is required
::math::statistics::pdfpareto scale shape value
Return the 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::pdfcauchy location scale value
Return the probability of a given value for a Cauchy distribution with given location and shape parameters. Note that the Cauchy distribution has no finite higherorder moments.
float location
 Location parameter
float scale
 Shape parameter
float value
 Value for which the probability is required
::math::statistics::pdflaplace location scale value
Return 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.
float location
 Location parameter (mean)
float scale
 Shape parameter
float value
 Value for which the probability is required
::math::statistics::pdfkumaraswamy a b value
Return 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.
float a
 Parameter a
float b
 Parameter b
float value
 Value for which the probability is required
::math::statistics::pdfnegativebinomial r p value
Return 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
::math::statistics::cdfnormal mean stdev value
Return 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.
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::cdflognormal mean stdev value
Return the cumulative probability of a given value for a lognormal distribution with given mean and standard deviation, that is the probability for values up to the given one.
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::cdfexponential mean value
Return the cumulative 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::cdfuniform xmin xmax value
Return the cumulative 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
::math::statistics::cdftriangular xmin xmax value
Return 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 pdftriangular
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::cdfsymmetrictriangular xmin xmax value
Return the cumulative 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::cdfstudentst degrees value
Return the cumulative probability of a given value for a Student's t distribution with given number of degrees.
int degrees
 Number of degrees of freedom
float value
 Value for which the probability is required
::math::statistics::cdfgamma alpha beta value
Return 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::cdfpoisson mu k
Return 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 occurences
::math::statistics::cdfbeta a b value
Return 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::cdfweibull scale shape value
Return 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::cdfgumbel location scale value
Return 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::cdfpareto scale shape value
Return 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::cdfcauchy location scale value
Return 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
 Value for which the probability is required
::math::statistics::cdfF nf1 nf2 value
Return the cumulative probability of a given value for an F distribution with nf1 and nf2 degrees of freedom.
float nf1
 Degrees of freedom for the numerator
float nf2
 Degrees of freedom for the denominator
float value
 Value for which the probability is required
::math::statistics::cdflaplace location scale value
Return the cumulative 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.
float location
 Location parameter (mean)
float scale
 Shape parameter
float value
 Value for which the probability is required
::math::statistics::cdfkumaraswamy a b value
Return the cumulative 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.
float a
 Parameter a
float b
 Parameter b
float value
 Value for which the probability is required
::math::statistics::cdfnegativebinomial r p value
Return the cumulative 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
 Greatest number of successes
::math::statistics::empiricaldistribution values
Return 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)
list values
 List of data to be examined
::math::statistics::randomnormal mean stdev number
Return a list of "number" random values satisfying a normal distribution with given mean and standard deviation.
float mean
 Mean value of the distribution
float stdev
 Standard deviation of the distribution
int number
 Number of values to be returned
::math::statistics::randomlognormal mean stdev number
Return a list of "number" random values satisfying a lognormal distribution with given mean and standard deviation.
float mean
 Mean value of the distribution
float stdev
 Standard deviation of the distribution
int number
 Number of values to be returned
::math::statistics::randomexponential mean number
Return a list of "number" random values satisfying an exponential distribution with given mean.
float mean
 Mean value of the distribution
int number
 Number of values to be returned
::math::statistics::randomuniform xmin xmax number
Return a list of "number" random values satisfying a uniform distribution with given extremes.
float xmin
 Minimum value of the distribution
float xmax
 Maximum value of the distribution
int number
 Number of values to be returned
::math::statistics::randomtriangular xmin xmax number
Return a list of "number" random values satisfying a triangular distribution with given extremes. If xmin < xmax, then lower values have a higher probability and vice versa (see also pdftriangular.
float xmin
 Minimum value of the distribution
float xmax
 Maximum value of the distribution
int number
 Number of values to be returned
::math::statistics::randomsymmetrictriangular xmin xmax number
Return a list of "number" random values satisfying a symmetric triangular distribution with given extremes.
float xmin
 Minimum value of the distribution
float xmax
 Maximum value of the distribution
int number
 Number of values to be returned
::math::statistics::randomgamma alpha beta number
Return a list of "number" random values satisfying a Gamma distribution with given shape and rate parameters.
float alpha
 Shape parameter
float beta
 Rate parameter
int number
 Number of values to be returned
::math::statistics::randompoisson mu number
Return a list of "number" random values satisfying a Poisson distribution with given mean.
float mu
 Mean of the distribution
int number
 Number of values to be returned
::math::statistics::randomchisquare df number
Return a list of "number" random values satisfying a chi square distribution with given degrees of freedom.
float df
 Degrees of freedom
int number
 Number of values to be returned
::math::statistics::randomstudentt df number
Return a list of "number" random values satisfying a Student's t distribution with given degrees of freedom.
float df
 Degrees of freedom
int number
 Number of values to be returned
::math::statistics::randombeta a b number
Return a list of "number" random values satisfying a Beta distribution with given shape parameters.
float a
 First shape parameter
float b
 Second shape parameter
int number
 Number of values to be returned
::math::statistics::randomweibull scale shape number
Return a list of "number" random values satisfying a Weibull distribution with given scale and shape parameters.
float scale
 Scale parameter
float shape
 Shape parameter
int number
 Number of values to be returned
::math::statistics::randomgumbel location scale number
Return a list of "number" random values satisfying a Gumbel distribution with given location and scale parameters.
float location
 Location parameter
float scale
 Scale parameter
int number
 Number of values to be returned
::math::statistics::randompareto scale shape number
Return a list of "number" random values satisfying a Pareto distribution with given scale and shape parameters.
float scale
 Scale parameter
float shape
 Shape parameter
int number
 Number of values to be returned
::math::statistics::randomcauchy location scale number
Return a list of "number" random values satisfying a Cauchy distribution with given location and scale parameters.
float location
 Location parameter
float scale
 Scale parameter
int number
 Number of values to be returned
::math::statistics::randomlaplace location scale number
Return a list of "number" random values satisfying 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.
float location
 Location parameter (mean)
float scale
 Shape parameter
int number
 Number of values to be returned
::math::statistics::randomkumaraswamy a b number
Return a list of "number" random values satisying 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.
float a
 Parameter a
float b
 Parameter b
int number
 Number of values to be returned
::math::statistics::randomnegativebinomial r p number
Return a list of "number" random values satisying a negative binomial distribution.
int r
 Allowed number of failures (at least 1)
float p
 Probability of success
int number
 Number of values to be returned
::math::statistics::histogramuniform xmin xmax limits number
Return the expected histogram for a uniform distribution.
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?
Evaluate the incomplete Gamma integral
1 / x p1
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.0e9)
::math::statistics::incompleteBeta a b x ?tol?
Evaluate the incomplete Beta integral
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.0e9)
::math::statistics::estimatepareto values
Estimate 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.
list values
 List of values, assumed to be distributed according to a Pareto distribution
::math::statistics::estimateexponential values
Estimate the parameter for the exponential distribution that comes closest to the given values. Returns an estimate of the one parameter and of the standard error.
list values
 List of values, assumed to be distributed according to an exponential distribution
::math::statistics::estimatelaplace values
Estimate 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.
list values
 List of values, assumed to be distributed according to an exponential distribution
::math::statistics::estimantenegativebinomial 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:
::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.
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.
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").

Routine PM  not implemented yet
PLOT PROCEDURES
The following simple plotting procedures are available:
::math::statistics::plotscale 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.
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::plotxydata 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.
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::plotxyline 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.
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::plottdata 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 timedependent 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::plottline canvas tdata tag
Create a simple XY plot in the given canvas  the data are shown as a line. See plottdata 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::plothistogram 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:
Fteststdev
intervalmeanstdev
histogramnormal
histogramexponential
testhistogram
testcorr
quantiles*
fouriercoeffs
fourierresiduals
oneparfunctionfit
oneparfunctionresiduals
plotlinearmodel
subdivide
EXAMPLES
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 printhistogram {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.02.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::basicstats $data1]
set b2 [::math::statistics::basicstats $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::plotscale .plot1 0 100 0 20
::math::statistics::plotscale .plot2 0 20 0 20
::math::statistics::plottline .plot1 $data1
::math::statistics::plottline .plot1 $data2
::math::statistics::plotxydata .plot2 $data1 $data2
puts "Correlation coefficient:"
puts [::math::statistics::corr $data1 $data2]
pause 2
puts "Plot histograms"
.plot2 delete all
::math::statistics::plotscale .plot2 0 20 0 100
set limits [::math::statistics::minmaxhistogramlimits 7 16]
set histogram_data [::math::statistics::histogram $limits $data1]
::math::statistics::plothistogram .plot2 $histogram_data $limits
puts "First series:"
printhistogram $histogram_data $limits
pause 2
set limits [::math::statistics::minmaxhistogramlimits 0 15 10]
set histogram_data [::math::statistics::histogram $limits $data2]
::math::statistics::plothistogram .plot2 $histogram_data $limits d2
.plot2 itemconfigure d2 fill red
puts "Second series:"
printhistogram $histogram_data $limits
puts "Autocorrelation function:"
set autoc [::math::statistics::autocorr $data1]
puts [::math::statistics::map $autoc {[format "%.2f" $x]}]
puts "Crosscorrelation function:"
set crossc [::math::statistics::crosscorr $data1 $data2]
puts [::math::statistics::map $crossc {[format "%.2f" $x]}]
::math::statistics::plotscale .plot1 0 100 1 4
::math::statistics::plottline .plot1 $autoc "autoc"
::math::statistics::plottline .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.
Bugs, Ideas, Feedback
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. 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.
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 leftmost button in the secondary navigation bar.
KEYWORDS
data analysis, mathematics, statistics
CATEGORY
Mathematics