statistics.js

https://thisancog.github.io/statistics.js/
Admin
A lightweight, open-source JavaScript library providing basic and advanced statistical utilities for...
Tokens:41,036
Snippets:288
Trust Score:8.3
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Statistics.js via NPM or Yarn

Source: https://thisancog.github.io/statistics.js/index.html

Install the statistics.js library using a package manager for use in your project.

```bash
$ npm install statistics.js
$ yarn add statistics.js
```

--------------------------------

### Require Statistics.js Module

Source: https://thisancog.github.io/statistics.js/index.html

Import the statistics.js module into your project after installation.

```javascript
var Statistics = require('/path/to/statistics.js');
```

--------------------------------

### Configure Statistics.js with Custom Settings

Source: https://thisancog.github.io/statistics.js/index.html

Pass a settings object to the Statistics constructor to customize library behavior. This example shows how to exclude specific columns, suppress warnings, and adjust z-table iterations.

```javascript
var settings = {
	excludeColumns: ["ID", "patientNumber"],
	suppressWarnings: true,
	zTableIterations: 15
};
var stats = new Statistics(data, columns, settings);
```

--------------------------------

### Calculate Binomial Distribution

Source: https://thisancog.github.io/statistics.js/inc/distributions.html

Computes the binomial distribution for a given n and probability. Use this to get an array of probabilities for k successes out of n trials.

```javascript
var distribution = stats.binomialDistribution(5, 0.5);
// probabilities of k = 0, 1, … 5 out of 5 coin tosses are heads
```

```javascript
var single = stats.binomialProbabilityMass(12, 22, 0.4);
// the probability of exactly 12 out of 22 succesful events,
// each with a probability to occur of 0.4
```

--------------------------------

### Calculate Poisson Distribution

Source: https://thisancog.github.io/statistics.js/inc/distributions.html

Computes the Poisson distribution for a given lambda. Use this to get an array of probabilities for observing k events.

```javascript
var distribution = stats.poissonDistribution(0.3);
// probabilities that an event which happens at a rate of 0.3 per time interval
// will be observed k = 0, 1, … times in that interval

var single = stats.poissonProbabilityMass(2, 4);
```

--------------------------------

### Calculate Binomial Cumulative Distribution

Source: https://thisancog.github.io/statistics.js/inc/distributions.html

Computes the binomial cumulative distribution for a given n and probability. Use this to get an array of probabilities for no more than k successes out of n trials.

```javascript
var distribution = stats.binomialCumulativeDistribution(5, 0.5);
// probabilities of k ≤ 0, 1, … 5 out of 5 coin tosses are heads
```

```javascript
var single = stats.binomialCumulativeValue(12, 22, 0.4);
// the probability of no more than 12 out of 22 succesful events,
// each with a probability to occur of 0.4
```

--------------------------------

### Calculate Student's t-Distribution

Source: https://thisancog.github.io/statistics.js/inc/distributions.html

Computes the Student's t-distribution for a given degree of freedom. Use this to get a distribution object covering values around zero.

```javascript
var distribution = stats.studentsTDistribution(12);
var single = stats.studentsTProbabilityDensity(0.7, 19);
```

--------------------------------

### Initialize Statistics.js with Data and Settings

Source: https://thisancog.github.io/statistics.js/index.html

Create a new Statistics object with your data, column information, and optional settings to begin analysis.

```javascript
var data = [
	{ ID: 1, age: 33 },
	{ ID: 2, age: 42 },
	{ ID: 3, age: 27 },
	…
];

var columns = {
	ID: 'ordinal',
	age: 'interval'
	…
};

var settings = { … };

var stats = new Statistics(data, columns, settings);

var meanAge = stats.arithmeticMean("age");
var stdDevAge = stats.standardDeviation("age");
```

--------------------------------

### Get Unique Values from Data

Source: https://thisancog.github.io/statistics.js/inc/core.html

Retrieves an ordered array of unique values from a dataset. The data can be a column name or an array of values.

```javascript
var uniques = stats.getUniqueValues([13, 4, 9, 7, 4, 5, 6, 13, 7, 5, 2, 1, 1, 3]);
```

--------------------------------

### showData()

Source: https://thisancog.github.io/statistics.js/inc/core.html

Displays stored data in the console. This method can log a specific column's data or the entire dataset as a table. If no input is provided, it logs the complete stored data.

```APIDOC
## showData()

### Description
This method is a simple wrapper for JavaScript's built-in `console.log()` and `console.table()` methods. If `input` is the name of a stored column then this will be logged, while the complete stored data will be logged in a table if no `input` is supplied. For any other `input`, this will simply be logged to console.

### Parameters
* **input** (any) - Optional. The name of a column to log, or any other value to log directly to the console.

### Usage
```javascript
var show = stats.showData();
```

### Returns
(undefined) - This method does not return a value; it logs output to the console.
```

--------------------------------

### Calculate Normal Cumulative Distribution

Source: https://thisancog.github.io/statistics.js/inc/distributions.html

Computes the cumulative normal distribution. Use this to get a distribution object for probabilities less than a given value.

```javascript
var distribution = stats.normalCumulativeDistribution();
var single = stats.normalCumulativeValue(1.4);
```

--------------------------------

### product()

Source: https://thisancog.github.io/statistics.js/inc/algebra.html

Computes the product of all numeric values in a dataset, ignoring non-numeric elements.

```APIDOC
## product()

### Description
Computes the product of all numeric values in the provided `data` array.

### Parameters
- **data** (string or array) - Required

### Usage
```javascript
var product = stats.product([1, 3, 7, 4, 12, true, 4, "a", 3, 6, 7, 1, 2]);
```

### Returns
```javascript
1016064 /* (true and "a" will be ignored) */
```
```

--------------------------------

### Calculate Normal Distribution

Source: https://thisancog.github.io/statistics.js/inc/distributions.html

Computes the normal distribution for a given mean and variance. Use this to get a distribution object covering values around the mean.

```javascript
var distribution = stats.normalDistribution(0, 0.3);
var single = stats.normalProbabilityDensity(1.4, 2, 4);
```

--------------------------------

### scatterPlot()

Source: https://thisancog.github.io/statistics.js/inc/core.html

Creates a simple scatter plot from provided data. It's useful for a quick visual overview but may have limitations with complex datasets. The method accepts data as an array of objects or an array of values, and various options to customize the plot appearance and behavior.

```APIDOC
## scatterPlot()

### Description
Provides an interface to create simple scatter plots of given `data`. It is intended to get a quick visual overview of data and thus is far from the precision and sophistication of dedicated plotting libraries.

### Parameters
* **data** (array) - Contains the data to be plotted either as an array of objects or an array of values. If an array of numeric values is supplied, the method will count the number of occurrences for each unique value and plot them. If you want to plot each value to its index, rather supply an object.

### Options
* **canvas** (canvas node) - Reference to a HTML5 canvas node in which the plot should be drawn, otherwise a new one will be created but not inserted into the DOM. (default: create new one)
* **xAxis** (string) - If `data` stores objects, then this will signify the name of the property to plot on the x axis.
* **yAxis** (string) - If `data` stores objects, then this will signify the name of the property to plot on the y axis.
* **height** (integer) - The height of the canvas. If omitted, it will be automatically sized. Minimum is `400` px. (default: automatically sized)
* **width** (integer) - The width of the canvas. If omitted, it will be automatically sized. Minimum is `400` px. (default: automatically sized)
* **dotRadius** (integer or float) - The data points’ radius. (default: 4)
* **showGrid** (boolean) - Determines if a grid should extend from the axes markers. (default: false)
* **minNumberXMarks** (integer) - The minimum amount of marks on the x axis. (default: 8)
* **minNumberYMarks** (integer) - The minimum amount of marks on the y axis. (default: 8)
* **background** (string) - The background color in the form of any valid CSS color string. (default: "#FFFFFF")
* **dotColor** (string) - The color for the data points in the form of any valid CSS color string. (default: "#000000")
* **gridColor** (string) - The grid color in the form of any valid CSS color string. (default: "#CCCCCC")
* **axisColor** (string) - The axis color in the form of any valid CSS color string. (default: "#000000")

### Usage
```javascript
var binomials = [
	{ k: 0, value: 0.01153 },
	{ k: 1, value: 0.05765 },
	{ k: 2, value: 0.13691 },
	{ k: 3, value: 0.20536 },
	…
];

var options = {
	xAxis: 'k',
	yAxis: 'value',
	width: 600,
	height: 600,
	dotColor: '#EE2211'
};

var plottedCanvas = stats.scatterPlot(binomials, options);
document.body.appendChild(plottedCanvas);
```

### Returns
(canvas node) - The canvas node on which the plot was drawn.
```

--------------------------------

### Include Statistics.js in Browser

Source: https://thisancog.github.io/statistics.js/index.html

Reference the minified statistics.js file in your HTML to use it in the browser.

```html
<script src="../path/to/statistics.min.js" type="text/javascript"></script>
```

--------------------------------

### Calculate Poisson Cumulative Distribution

Source: https://thisancog.github.io/statistics.js/inc/distributions.html

Computes the cumulative Poisson distribution for a given lambda. Use this to get an array of cumulative probabilities for observing up to k events.

```javascript
var distribution = stats.poissonCumulativeDistribution(0.3);
// probabilities that an event which happens at a rate of 0.3 per time interval
// will be observed up to k = 0, 1, … times in that interval

var single = stats.poissonCumulativeValue(2, 4);
```

--------------------------------

### ziggurat()

Source: https://thisancog.github.io/statistics.js/inc/error.html

Generates pseudo-random numbers from a normal distribution using the Ziggurat algorithm. This implementation cannot be initialized with a seeding source.

```APIDOC
## ziggurat()

### Description
Generates pseudo-random numbers from a normal distribution with `mean` and `standardDeviation`. It is similar to the Box-Muller generator, however, it can not be initialised with a seeding source. Numbers can be generated with the `next()` method invoked on the new ziggurat object.

### Parameters:
- **mean** (integer or float) - Optional - Default: 0
- **standardDeviation** (integer or float) - Optional - Default: 1

### Usage:
```javascript
var ziggurat = new stats.ziggurat(5, 1);
var random = ziggurat.next();
```

### Returns:
(number) - A pseudo-random number from a normal distribution.

```
4.72130…
```
```

--------------------------------

### xorshift()

Source: https://thisancog.github.io/statistics.js/inc/error.html

Generates pseudo-random numbers from a uniform distribution using a four-seed XORshift algorithm. It allows skipping initial numbers and generating normalized values.

```APIDOC
## xorshift()

### Description
Generates pseudo-random numbers from a uniform distribution based on an array `seed` of exactly four numeric seeds. You may supply a `startIndex` of `n` to skip the first `n` generated numbers. Numbers can be generated with the `next(normalise = true)` method invoked on the new xorshift object.

### Parameters:
- **seed** (array) - Required - An array of exactly four numeric seeds.
- **startIndex** (integer) - Optional - Default: 0

### Usage:
```javascript
var xorshift = new stats.xorshift([100934093, 482920221, 592807725, 993051833]);
var random = xorshift.next(false);
var randomNormalised = xorshift.next(true);
```

### Returns:
(number) - A pseudo-random number. If `normalise` is true, the number is in the interval [0, 1).

```
random: 471695451
randomNormalised: 0.27623…
```
```

--------------------------------

### Display Data in Console

Source: https://thisancog.github.io/statistics.js/inc/core.html

Logs a specific column or the entire dataset to the console using console.log and console.table. Useful for debugging and inspecting data.

```javascript
var show = stats.showData();
```

--------------------------------

### regularisedBeta()

Source: https://thisancog.github.io/statistics.js/inc/algebra.html

Computes the regularised beta function of three values x, a, and b, which is the ratio of the lower incomplete beta function to the complete beta function.

```APIDOC
## regularisedBeta()

### Description
Computes the regularised beta function of `x`, `a`, and `b`.

### Parameters
- **x** (integer or float) - Required
- **a** (integer or float) - Required
- **b** (integer or float) - Required

### Usage
```javascript
var regularisedBeta = stats.regularisedBeta(0.75, 4.2, 3);
```

### Returns
```javascript
0.27207...
```
```

--------------------------------

### Data Entry Format

Source: https://thisancog.github.io/statistics.js/index.html

Structure your data as an array of objects, where each object represents a record with key-value pairs for variables.

```javascript
var data = [
	{ age: 32, agreement: 'none', iq: 104 },
	{ age: 45, agreement: 'somewhat', iq: 110 },
	…
];
```

--------------------------------

### sumExact()

Source: https://thisancog.github.io/statistics.js/inc/algebra.html

Computes the sum of all the values in a dataset using Kahan's algorithm for accurate floating-point summation. Elements that are not integers, floating point numbers, or number strings will be ignored.

```APIDOC
## sumExact(data)

### Description
Computes the sum of all the values in a dataset using Kahan's algorithm for accurate floating-point summation. Elements that are not integers, floating point numbers, or number strings will be ignored.

### Parameters
#### Path Parameters
- **data** (string or array) - Required - The dataset to sum.

### Usage
```javascript
var sumExact = stats.sumExact([12.3, 9.0, 14.2, "a", 22.98, 0, -12.0000003, true]);
```

### Returns
```
46.4799997 /* ("a" and true will be ignored) */
```
```

--------------------------------

### contingencyTable()

Source: https://thisancog.github.io/statistics.js/inc/core.html

Creates a contingency table for two specified columns, showing counts for each pairing and overall totals. Can also output specific values (a, b, c, d) for 2x2 tables.

```APIDOC
## contingencyTable()

### Description
Creates a contingency table of the stored data for two nominal or ordinal variables given by `firstColumn` and `secondColumn` and returns a nested object with the individual counts for each pairing, total counts, and in case of only two unique values for each variable the individual fields represented as `a, b, c, d`.

### Parameters
*   **firstColumn** (string) - Required - The name of the first column for the contingency table.
*   **secondColumn** (string) - Required - The name of the second column for the contingency table.

### Usage
```javascript
var testData = [
	{ gender: 'male', agreement: 'no' },
	{ gender: 'male', agreement: 'no' },
	{ gender: 'male', agreement: 'no' },
	{ gender: 'male', agreement: 'no' },
	{ gender: 'male', agreement: 'yes' },
	{ gender: 'male', agreement: 'yes' },
	{ gender: 'male', agreement: 'yes' },
	{ gender: 'female', agreement: 'no' },
	{ gender: 'female', agreement: 'yes' },
	{ gender: 'female', agreement: 'yes' },
	{ gender: 'female', agreement: 'yes' },
	{ gender: 'female', agreement: 'yes' }
];

var testVars = { gender: 'nominal', agreement: 'nominal' };
var stats = new Statistics(testData, testVars);
var contingencyTable = stats.contingencyTable('gender', 'agreement');
```

### Response Example
```json
{
	"detailled": {
		female: {
			no: 1,
			yes: 2,
			total: 3
		},
		male: {
			no: 4,
			yes: 3,
			total: 7
		},
		total: {
			female: 3,
			male: 7,
			no: 5,
			yes: 5,
			total: 10
		}
	},
	a: 4,
	b: 3,
	c: 1,
	d: 2
}
```
```

--------------------------------

### binomialDistribution()

Source: https://thisancog.github.io/statistics.js/inc/distributions.html

Computes the binomial distribution for a given n and probability. It returns an array of probabilities for k successes out of n trials.

```APIDOC
## binomialDistribution()

### Description
Computes the binomial distribution for a given `n` and `probability`. The element at index `k` corresponds to the probability that out of `n` independent trials, exactly `k` are successful, when each trial has an individual `probability`. Returns an array of floating point numbers with their indices.

### Parameters
- **n** (integer) - Optional, default: 10
- **probability** (integer or float) - Optional, default: 0.5

### Usage
```javascript
var distribution = stats.binomialDistribution(5, 0.5);
// probabilities of k = 0, 1, … 5 out of 5 coin tosses are heads
```

### Returns
- **distribution** (array) - An array of probabilities for each possible number of successes.
```json
[ 0.03125, 0.15625, 0.3125, 0.3125, 0.15625, 0.03125 ]
```
```

--------------------------------

### median()

Source: https://thisancog.github.io/statistics.js/inc/measures.html

Retrieves the median of a dataset.

```APIDOC
## median()

### Description
Retrieves the median of a dataset.

### Parameters
- **data** (string or array) - Required - The dataset to retrieve the median from.

### Scales of measure
ordinal, interval, metric

### Usage:
```
var median = stats.median([1, 3, 7, 4, 12, 4, 4, 7, 3, 6, 7, 1, 2]);
```

### Returns:
(number) The median of the dataset.

### Example Response:
```
4
```
```

--------------------------------

### reset()

Source: https://thisancog.github.io/statistics.js/inc/core.html

Deletes all loaded data while retaining scale information, value maps, settings, and stored calculations. Returns true on success.

```APIDOC
## reset()

### Description
Deletes all the data previously loaded, but keeps information about the scales of measure for each column, value maps, settings and all stored calculations (e.g. larger factorials, the z-table). Returns true on success.

### Usage
```javascript
stats.reset();
```

### Returns
- **boolean** - `true` on successful reset.

### Response Example
```json
true
```
```

--------------------------------

### studentsTTestOneSample()

Source: https://thisancog.github.io/statistics.js/inc/tests.html

Computes Student’s one sample t-test to examine if the arithmetic mean of a sample is equal to a predefined mean. Returns the t-statistic, degrees of freedom, and probabilities.

```APIDOC
## studentsTTestOneSample()

### Description
Computes Student’s one sample t-test for the values of a variable given by `column`. It examines if the arithmetic mean of a sample `column` is equal to the predefined or suspected arithmetic mean `nullHypothesisMean`. This method returns the associated t-statistic, the degrees of freedom and both one- and two-sided probabilities that the given observation can be made if the null hypothesis of equal arithmetic means is to hold true.

### Parameters:
- **column** (string) - Required
- **nullHypothesisMean** (integer or float) - Required

### Scales of measure:
interval, metric

### Usage:
```javascript
var batchMeasurements = [
	{ weight: 185 },
	{ weight: 201 },
	{ weight: 193 },
	{ weight: 184 },
	{ weight: 180 },
	{ weight: 176 },
	{ weight: 193 },
	{ weight: 182 },
	{ weight: 197 },
	{ weight: 204 }
];

var stats = new Statistics(batchMeasurements, { weight: 'metric' });
var oneSample = stats.studentsTTestOneSample('weight', 200);
```

### Returns:
```json
{
	tStatistic: -3.51631…,
	degreesOfFreedom: 9,
	pOneSided: 0.00327…,
	pTwoSided: 0.00655…
}
```
```

--------------------------------

### beta()

Source: https://thisancog.github.io/statistics.js/inc/algebra.html

Computes the beta function of two values a and b. If both variables have an integer value, factorials are computed instead of the gamma function to avoid potential errors.

```APIDOC
## beta()

### Description
Computes the beta function of two values `a` and `b`.

### Parameters
- **a** (integer or float) - Required
- **b** (integer or float) - Required

### Usage
```javascript
var beta = stats.beta(4.2, 3);
```

### Returns
```javascript
0.01477...
```
```

--------------------------------

### factorial()

Source: https://thisancog.github.io/statistics.js/inc/algebra.html

Retrieves or computes the nth factorial. If n is a floating point number, the result of the gamma() function will be returned.

```APIDOC
## factorial()

### Description
Computes the factorial of a number `n`. If `n` is a float, it uses the gamma function.

### Parameters
- **n** (integer or float) - Required

### Usage
```javascript
var factorial = stats.factorial(16);
```

### Returns
```javascript
20922789888000
```
```

--------------------------------

### incompleteBeta()

Source: https://thisancog.github.io/statistics.js/inc/algebra.html

Computes the lower incomplete beta function of three values x, a, and b over a specified interval.

```APIDOC
## incompleteBeta()

### Description
Computes the lower incomplete beta function of `x`, `a`, and `b`.

### Parameters
- **x** (integer or float) - Required
- **a** (integer or float) - Required
- **b** (integer or float) - Required

### Usage
```javascript
var incompleteBeta = stats.incompleteBeta(0.75, 4.2, 3);
```

### Returns
```javascript
0.01205...
```
```

--------------------------------

### addData()

Source: https://thisancog.github.io/statistics.js/inc/core.html

Adds multiple rows of new data to the existing dataset. The new data must have the same columns as the existing data. Returns true on success.

```APIDOC
## addData()

### Description
Adds several rows of new data to the existing data to work with. All the elements of `data` or, if `data` is a JSON encoded string the array it evaluates to, need to have the same columns as the rest of the already existing data.

### Parameters
*   **dataset** (array or JSON encoded string) - Required - The data to add.

### Returns
*   **boolean** - `true` on success.

### Usage
```javascript
stats.addData([{age: 22, gender: "male", "heartFrequency": 89}, {age: 37, gender: "female", "heartFrequency": 76}]);
```

### Response Example
```json
true
```
```

--------------------------------

### Add Multiple Data Rows

Source: https://thisancog.github.io/statistics.js/inc/core.html

Use `addData` to append several new data entries to your dataset. Ensure new data matches existing column structures. Returns `true` on success.

```javascript
stats.addData([{age: 22, gender: "male", "heartFrequency": 89}, {age: 37, gender: "female", "heartFrequency": 76}]);
```

--------------------------------

### poissonDistribution(lambda)

Source: https://thisancog.github.io/statistics.js/inc/distributions.html

Computes the Poisson distribution for a given lambda. Returns an array of floating point numbers representing probabilities for k = 0, 1, 2, ...

```APIDOC
## poissonDistribution(lambda)

### Description
Computes the Poisson distribution for a given `lambda`. Returns an array of floating point numbers with their indices `k` for `k` such as `P(X=k)` (with the threshold parameter epsilon).

### Parameters
- **lambda** (integer or float) - Optional, default: 1

### Usage
```
var distribution = stats.poissonDistribution(0.3);
```

### Returns
An array of probabilities for the Poisson distribution, e.g.:
```
distribution: [ 0.74081…, 0.22224…, 0.03333…, ... ]
```
```

--------------------------------

### Generate Normal Distribution Numbers with Ziggurat

Source: https://thisancog.github.io/statistics.js/inc/error.html

Generates pseudo-random numbers from a normal distribution with specified mean and standard deviation. This generator cannot be initialized with a seeding source.

```javascript
var ziggurat = new stats.ziggurat(5, 1);
var random = ziggurat.next();
```

--------------------------------

### Retrieve Column Scale

Source: https://thisancog.github.io/statistics.js/inc/core.html

Use `getScale` to find out the scale of measurement (e.g., interval, nominal) for a given column.

```javascript
var scale = stats.getScale("age");
```

--------------------------------

### Define Columns with Scales and Value Maps

Source: https://thisancog.github.io/statistics.js/index.html

Specify variable scales of measurement (nominal, ordinal, interval, metric) and optional value maps for ordinal data.

```javascript
var columns = {
	age: 'metric',
	agreement: {
		scale: 'ordinal',
		valueMap: ['none', 'somewhat', 'undecided', 'much', 'total']
	},
	iq: 'metric'
};

var stats = new Statistics(data, columns);
```

--------------------------------

### sum()

Source: https://thisancog.github.io/statistics.js/inc/algebra.html

Computes the sum of all the values in a dataset that can be either the name of a column or an array of values. Elements that are not integers, floating point numbers, or number strings will be ignored.

```APIDOC
## sum(data)

### Description
Computes the sum of all the values in a dataset that can be either the name of a column or an array of values. Elements that are not integers, floating point numbers, or number strings will be ignored. Consider using sumExact() for floating point numbers, as JavaScript might compute wrong results.

### Parameters
#### Path Parameters
- **data** (string or array) - Required - The dataset to sum.

### Usage
```javascript
var sum = stats.sum([12, 9, 14, "a", 22, 0, -12, true]);
```

### Returns
```
45 /* ("a" and true will be ignored) */
```
```

--------------------------------

### quantile()

Source: https://thisancog.github.io/statistics.js/inc/measures.html

Computes the quantiles of the values in a dataset. The scale of measure must be ordinal or higher.

```APIDOC
## quantile()

### Description
Computes the quantiles of the values in a dataset `data` that can be either the name of a column (string) or an array of values. The `percentage` should be given as an integer or floating point number between `0` and `1`. If the scale of measure of the column given by `data` is not ordinal or of higher order, it will return `undefined` and throw an error.

### Parameters
* **data** (string or array) - Required - The dataset to compute the quantiles from.
* **percentage** (integer or float) - Required - The percentage for which to compute the quantile (between 0 and 1).

### Scales of measure
ordinal, interval, metric

### Usage
```javascript
var quantile = stats.quantile([1, 3, 7, 4, 12, 4, 4, 7, 3, 6, 7, 1, 2], 0.33);
```

### Returns
(integer or float) The quantile value for the given percentage.

### Example Response
```json
3
```
```

--------------------------------

### gamma()

Source: https://thisancog.github.io/statistics.js/inc/algebra.html

Computes the gamma function for a given n. It can use either Stirling-Nemes or Spouge's approximation for calculation.

```APIDOC
## gamma()

### Description
Computes the gamma function for a given `n`.

### Parameters
- **n** (integer or float) - Required
- **moreExact** (boolean) - Optional, default: false

### Usage
```javascript
var gamma = stats.gamma(4.32, true);
```

### Returns
```javascript
9.09595...
```
```

--------------------------------

### Shuffle Array with Fisher-Yates Algorithm

Source: https://thisancog.github.io/statistics.js/inc/error.html

Shuffles the values in a dataset (array or column name) using Durstenfeld's version of the Fisher-Yates shuffle algorithm. A custom random number generator can be provided.

```javascript
var fisherYatesShuffle = stats.fisherYatesShuffle([1, 3, 7, 4, 12, 4, 4, 7, 3, 6, 7, 1, 2]);
```

--------------------------------

### Generate Uniform Distribution Numbers with Xorshift

Source: https://thisancog.github.io/statistics.js/inc/error.html

Generates pseudo-random numbers from a uniform distribution using an array of four seeds. Allows skipping initial numbers and choosing between raw or normalized values.

```javascript
var xorshift = new stats.xorshift([100934093, 482920221, 592807725, 993051833]);
var random = xorshift.next(false);
var randomNormalised = xorshift.next(true);
```

--------------------------------

### fisherYatesShuffle()

Source: https://thisancog.github.io/statistics.js/inc/error.html

Shuffles the values in a dataset (array or column name) using the Fisher-Yates algorithm. It returns a random permutation of the values.

```APIDOC
## fisherYatesShuffle()

### Description
Shuffles the values in a dataset `data` that can be either the name of a column (string) or an array of values according to Durstenfeld’s version. It returns a random permutation of the values as an `array` based on a random number generator `randomSource`.

### Parameters:
- **data** (string or array) - Required
- **randomSource** (function) - Optional - Default: Math.random

### Usage:
```javascript
var fisherYatesShuffle = stats.fisherYatesShuffle([1, 3, 7, 4, 12, 4, 4, 7, 3, 6, 7, 1, 2]);
```

### Returns:
(array) - A randomly permuted array of the input data.

```
[6, 2, 1, 3, 4, 7, 4, 3, 7, 4, 12, 7, 1]
```
```

--------------------------------

### getScale()

Source: https://thisancog.github.io/statistics.js/inc/core.html

Retrieves the scale of measurement (e.g., interval, nominal) for a specified column.

```APIDOC
## getScale()

### Description
Retrieves the scale of measurement for a column `column`. See also the explanation of the different scales.

### Parameters
*   **column** (string) - Required - The name of the column to get the scale for.

### Usage
```javascript
var scale = stats.getScale("age");
```

### Response Example
```json
"interval"
```
```

--------------------------------

### Calculate Quantile

Source: https://thisancog.github.io/statistics.js/inc/measures.html

Computes the quantile for a dataset given a percentage. The percentage must be between 0 and 1. The data scale must be ordinal or higher.

```javascript
var quantile = stats.quantile([1, 3, 7, 4, 12, 4, 4, 7, 3, 6, 7, 1, 2], 0.33);
```

--------------------------------

### Calculate Binomial Coefficient

Source: https://thisancog.github.io/statistics.js/inc/algebra.html

Computes the binomial coefficient 'n choose k', representing the number of ways to choose k items from a set of n items without regard to the order.

```javascript
var nChooseK = stats.binomialCoefficient(7, 3);
```

--------------------------------

### regularisedGamma()

Source: https://thisancog.github.io/statistics.js/inc/algebra.html

Computes the regularised gamma function of two values s and x over the interval [0, infinity). It corresponds to the ratio of the lower incomplete gamma function and the complete gamma function.

```APIDOC
## regularisedGamma(s, x)

### Description
Computes the regularised gamma function of two values s and x over the interval [0, infinity). It corresponds to the ratio of the lower incomplete gamma function and the complete gamma function.

### Parameters
#### Path Parameters
- **s** (integer or float) - Required - The first value for the gamma function.
- **x** (integer or float) - Required - The second value for the gamma function.

### Usage
```javascript
var regularisedGamma = stats.regularisedGamma(0.75, 4.2);
```

### Returns
```
0.99185…
```
```

--------------------------------

### binomialTest()

Source: https://thisancog.github.io/statistics.js/inc/tests.html

Computes the binomial test for the values of a nominal or ordinal, dichotomous variable. It returns the probability of observing the given data if the event `valueToTest` occurs with a probability of `alpha`. Results include probabilities for exactly, fewer than or exactly, and more than or exactly the observed events.

```APIDOC
## binomialTest()

### Description
Computes the binomial test for the values of a nominal or ordinal, dichotomous variable. It returns the probability of observing the given data if the event `valueToTest` occurs with a probability of `alpha`. Results include probabilities for exactly, fewer than or exactly, and more than or exactly the observed events.

### Parameters:
- **data** (string or array) - Required - The name of the column or an array of values.
- **valueToTest** (string) - Required - The specific value to test.
- **alpha** (integer or float) - Optional, default: 0.5 - The assumed probability of the event.

### Scales of measure:
nominal, ordinal

### Returns:
An object containing the probabilities for different outcomes.

```json
{
	"pExactly": "number",
	"pFewer": "number",
	"pAtMost": "number",
	"pMore": "number",
	"pAtLeast": "number"
}
```

### Usage:
```javascript
// results of a medical procedure - probability to survive: 80%
// how likely is it that only 5/12 patients survived?
var testData = [
	{ survival: 'no' },
	{ survival: 'no' },
	{ survival: 'no' },
	{ survival: 'no' },
	{ survival: 'no' },
	{ survival: 'no' },
	{ survival: 'no' },
	{ survival: 'yes' },
	{ survival: 'yes' },
	{ survival: 'yes' },
	{ survival: 'yes' },
	{ survival: 'yes' }
];

var testVars = { survival: { scale: 'nominal', valueMap: ['no', 'yes'] }};

var stats = new Statistics(testData, testVars);
var binomial = stats.binomialTest('survival', 'yes', 0.8);
```
```

--------------------------------

### minimum()

Source: https://thisancog.github.io/statistics.js/inc/measures.html

Finds the smallest value in a dataset. The scale of measure must be ordinal or higher.

```APIDOC
## minimum()

### Description
Finds the smallest among the values in a dataset `data` that can be either the name of a column (string) or an array of values. If the scale of measure of the column given by `data` is not ordinal or of higher order, it will return `undefined` and throw an error.

### Parameters
* **data** (string or array) - Required - The dataset to find the minimum value from.

### Scales of measure
ordinal, interval, metric

### Usage
```javascript
var min = stats.minimum([1, 3, 7, 4, 12, 4, 4, 7, 3, 6, 7, 1, 2]);
```

### Returns
(integer or float) The minimum value in the dataset.

### Example Response
```json
1
```
```

--------------------------------

### Calculate Incomplete Beta Function

Source: https://thisancog.github.io/statistics.js/inc/algebra.html

Computes the lower incomplete beta function. This method uses a continued fraction representation for fast convergence. The number of iterations can be adjusted.

```javascript
var incompleteBeta = stats.incompleteBeta(0.75, 4.2, 3);
```

--------------------------------

### binomialCoefficient()

Source: https://thisancog.github.io/statistics.js/inc/algebra.html

Computes the binomial coefficient for two integers n and k, representing the number of ways to choose k items from a set of n items.

```APIDOC
## binomialCoefficient()

### Description
Computes the binomial coefficient `nCk` for two integers `n` and `k`.

### Parameters
- **n** (integer) - Required
- **k** (integer) - Required

### Usage
```javascript
var nChooseK = stats.binomialCoefficient(7, 3);
```

### Returns
```javascript
35
```
```

--------------------------------

### Sort Data by Column with Options

Source: https://thisancog.github.io/statistics.js/inc/core.html

Sorts data by a specified column, with options to sort in descending order and optionally modify the original data. Handles integers, floats, and number strings.

```javascript
var sorted = stats.sortDataByColumn('age', { order: 'desc' });
```

--------------------------------

### kendallsTau()

Source: https://thisancog.github.io/statistics.js/inc/correlation.html

Computes the Kendall rank correlation coefficient (Kendall’s tau) for two variables. This method returns an object with three parameters: Tau a (for no ties), Tau b (accounts for ties), and Tau c (suitable for rectangular cases). Each parameter includes its respective tau value, z statistic, and probabilities.

```APIDOC
## kendallsTau()

### Description
Computes the Kendall rank correlation coefficient (in short, Kendall’s tau) for two variables given by `firstColumn` and `secondColumn`. It it similar to Spearman’s rho, however, it does not account for the rank differences but for their comparisons. It is usually smaller than Spearman’s rho, but is a more robust measure if the variables are not normally distributed, their scales are very different or if the small sample size is small.  

This method returns an object for three different parameters Tau a, Tau b and Tau c, all of which defined over a range of [-1, 1], with a value of -1 implying total disagreement, a value of 0 for total independence and a value of 1 for total agreement between two variables.
* _Tau a_ : only defined if no ties are present. In that case, the value for tau, the statistic z and the one- and two-sided probabilities for statistical independence under the assumption of a normally distributed null hypothesis are returned.
* _Tau b_ : more robust than Tau a as it accounts for tied values. If no ties are present, its value and all subsequent measures will be equal to those of Tau a. Its value, the statistic z and the one- and two-sided probabilities for statistical independence under the assumption of a normally distributed null hypothesis are returned.
* _Tau c_ : similar to Tau b but more suitable for rectangular cases as the former rarely reaches its extreme values.

### Parameters:
- **firstColumn** (string) - Required
- **secondColumn** (string) - Required

### Scales of measure:
ordinal, interval, metric

### Usage:
```javascript
var testData = … // same data as in the example for the goodmanKruskalsGamma() method
var testVars = … // same data as in the example for the goodmanKruskalsGamma() method

var stats = new Statistics(testData, testVars);
var kendall = stats.kendallsTau('satisfaction', 'affordability');
```

### Returns:
```json
{
	a: {
		tauA: 0.68888…,
		z: 2.77272…,
		pOneSided: 0.00278,
		pTwoSided: 0.00556
	},
	b: {
		tauB: 0.68888…,
		z: 2.77272…,
		pOneSided: 0.00278,
		pTwoSided: 0.00556
	},
	c: {
		tauC: 1.24
	},
	missings: 0
}
```
```

--------------------------------

### reduceToPairs()

Source: https://thisancog.github.io/statistics.js/inc/core.html

Returns values for datasets that have valid data in both specified columns, along with counts of total datasets and those with missing values.

```APIDOC
## reduceToPairs()

### Description
Returns the values of those datasets that have valid data for both `firstColumn` and `secondColumn` along with their total count and the number of datasets with missing values.

### Parameters
- **firstColumn** (string) - Required - The name of the first column.
- **secondColumn** (string) - Required - The name of the second column.

### Usage
```javascript
var reduced = stats.reduceToPairs('age', 'gender');
```

### Returns
- **object** - An object containing the reduced data.

### Response Example
```json
{
	"length": 18,
	"missings": 2,
	"valuesFirst": [ 27, 24, … ],
	"valuesSecond": [ 'male', 'male', … ],
	"valuesCombined": [
		{
			age: 22,
			gender: 'male'
		},
		{
			age: 24,
			gender: 'male'
		},
		…
	]
}
```
```

--------------------------------

### getColumn()

Source: https://thisancog.github.io/statistics.js/inc/core.html

Retrieves all values from a specified column and returns them as an array.

```APIDOC
## getColumn()

### Description
Returns the values of the column `dataset` in an array.

### Parameters
*   **column** (string) - Required - The name of the column to retrieve.

### Usage
```javascript
var ageColumn = stats.getColumn('age');
```

### Response Example
```json
[ 22, 34, 27, 19, 27, 24, 37, 42, 45, 37 ]
```
```

--------------------------------

### Retrieve Column Data

Source: https://thisancog.github.io/statistics.js/inc/core.html

Use `getColumn` to extract all values from a specified column into an array.

```javascript
var ageColumn = stats.getColumn('age');
```

--------------------------------

### frequencies()

Source: https://thisancog.github.io/statistics.js/inc/measures.html

Sorts dataset values in descending order and returns them with their absolute and relative frequencies.

```APIDOC
## frequencies()

### Description
Sorts the values in a dataset `data` that can be either the name of a column (string) or an array of values in descending order and returns them with their absolute and relative (in the range of `0` and `1`) frequencies.

### Parameters
- **data** (string or array) - Required - The dataset to analyze.

### Scales of measure
nominal, ordinal, interval, metric

### Usage
```javascript
var frequencies = stats.frequencies(["male", "female", "male", "male", "female", "female", "indeterminate", "female"]);
```

### Returns
(array) An array of objects, each containing a value, its absolute frequency, and its relative frequency.

### Response Example
```json
[
	{ value: "female", absolute: 4, relative: 0.5 },
	{ value: "male", absolute: 3, relative: 0.375 },
	{ value: "indeterminate", absolute: 1, relative: 0.125 }
]
```
```

--------------------------------

### sort()

Source: https://thisancog.github.io/statistics.js/inc/core.html

Sorts an array of values. This method is type-agnostic and handles integers, floating-point numbers, and number strings. It supports both ascending and descending order.

```APIDOC
## sort()

### Description
A simple sorting method that is type agnostic for integers, floating point numbers and number strings. Setting `order` to `"desc"` will result in descending order.

### Parameters
* **values** (array) - Required. The array of values to sort.
* **order** (string) - Optional. The sort order, either `"asc"` (ascending) or `"desc"` (descending). (default: "asc")

### Usage
```javascript
var sorted = stats.sort([1, 3, 7, 4, 12, "4", 4, 7, "9", 6, 7, 1, 2]);
```

### Returns
(array) - A new array containing the sorted values.
```

--------------------------------

### Create a Scatter Plot

Source: https://thisancog.github.io/statistics.js/inc/core.html

Generates a simple scatter plot from an array of objects or values. Useful for a quick visual overview of data. Ensure data properties for axes are numerical.

```javascript
var binomials = [
	{ k: 0, value: 0.01153 },
	{ k: 1, value: 0.05765 },
	{ k: 2, value: 0.13691 },
	{ k: 3, value: 0.20536 },
	…
];

var options = {
	xAxis: 'k',
	yAxis: 'value',
	width: 600,
	height: 600,
	dotColor: '#EE2211'
};

var plottedCanvas = stats.scatterPlot(binomials, options);
document.body.appendChild(plottedCanvas);
```

--------------------------------

### Calculate Incomplete Gamma Function

Source: https://thisancog.github.io/statistics.js/inc/algebra.html

Computes the lower incomplete gamma function. Similar to the incomplete beta function, this method uses a continued fraction representation for efficient computation. Iterations can be configured.

```javascript
var incompleteGamma = stats.incompleteGamma(0.75, 4.2);
```

--------------------------------

### Calculate Kendall's Tau Variants

Source: https://thisancog.github.io/statistics.js/inc/correlation.html

Compute Kendall's Tau (a, b, and c) for rank correlation. Tau b is recommended for its robustness to ties, while Tau a is suitable for data without ties, and Tau c is better for rectangular cases.

```javascript
var testData = … // same data as in the example for the goodmanKruskalsGamma() method
var testVars = … // same data as in the example for the goodmanKruskalsGamma() method

var stats = new Statistics(testData, testVars);
var kendall = stats.kendallsTau('satisfaction', 'affordability');
```
Tokens:
Raw