> For the complete documentation index, see [llms.txt](https://docs.rulecube.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rulecube.com/v2.5/language-reference/statistics.md).

# Statistics

Collection of statistical functions.

### Methods

#### mean

```javascript
mean(values: number[])
```

Calculates the average for given array of values.

**Parameters**

    **values *****number\[]***

        The array of values on which the calculation is made.

**Return type**

    number

**Examples**

```javascript
// Calculates the mean for a number of given values:
Statistics.mean([1, 2, 3, 4, 5, 6, 7, 8, 9, 25]) // => 7 (Calculates mean for values 1, 2, 3, 4, 5, 6, 7, 8, 9 and 25)
```

#### mode

```javascript
mode(values: number[])
```

Calculates the most frequent occurring value(s) within a given array. Returns a single value. In the case of multiple modes, this will return the lowest value.

**Parameters**

    **values *****number\[]***

        The array of values on which the mode is deducted.

**Return type**

    number

**Examples**

```javascript
// Calculates the mode for a number of given values:
Statistics.mode([1, 2, 3, 4, 4, 6, 7, 8, 9, 25]) // => 4
// Calculates the mode for a number of given values:
Statistics.mode([1, 2, 3, 4, 4, 6, 7, 7, 9, 25]) // => 4 (4 and 7 are the mode, but 4 is lowest value and is returned)
```

#### modes

```javascript
modes(values: number[])
```

Calculates the most frequent occurring value(s) within a given array. Returns an array.

**Parameters**

    **values *****number\[]***

        The array of values on which the mode is deducted.

**Return type**

    number\[]

**Examples**

```javascript
// Calculates the mode for a number of given values:
Statistics.modes([1, 2, 3, 4, 4, 6, 7, 8, 9, 25]) // => [4]
// Calculates the mode for a number of given values:
Statistics.modes([1, 2, 3, 4, 4, 6, 7, 7, 9, 25]) // => [4, 7]
```

#### median

```javascript
median(values: number[])
```

Returns the median, or the number in the middle of the given array.

**Parameters**

    **values *****number\[]***

        The array of values on which the median is calculated.

**Return type**

    number

**Examples**

```javascript
// Calculates the median for a number of given values:
Statistics.median([1, 2, 3, 4, 5, 6, 7, 8, 9, 25]) // => 5.5 (Calculates median for values 1, 2, 3, 4, 5, 6, 7, 8, 9 and 25)
```

#### slope

```javascript
slope(knownYvalues: number[], knownXvalues?: number[])
```

Calculates the slope for a given number of points. If the x-values are omitted, the assumption is that all x-values have corresponding consecutive y-values \[1 .. nr of x-values]. X-values may be numeric or of type Year ("YYYY") or YearMonth ("YYYY-MM").

**Parameters**

    **knownYvalues *****number\[]***

        The array of values on which the calculation is made.

    **knownXvalues *****number\[]***

        (optional) The x-values array. If omitted, the x-values are generated as 1,2,3...n for the number of y-values

**Return type**

    number

**Examples**

```javascript
// Calculates slope for a number of given points:
Statistics.slope([2,4,6,8,10]) // => 2 (Calculates slope for points 2, 4, 6, 8 and 10)
// Calculates slope for a number of given points and given x-values:
Statistics.slope([2,4,6,8,10], [1,3,5,7,9]) // => 1 (Calculates slope for points (1,2), (3,4), (5,6), (7,8) and (9,10))
```

#### intercept

```javascript
intercept(knownYvalues: number[], knownXvalues?: number[])
```

Calculates the intercept (the value at the intersection of the y axis) of the linear regression line through a supplied set of x-values. If the x-values are omitted, the assumption is that all x-values have corresponding consecutive y-values \[1 .. nr of x-values]. X-values may be numeric or of type Year ("YYYY") or YearMonth ("YYYY-MM")

**Parameters**

    **knownYvalues *****number\[]***

        The array of values on which the calculation is made.

    **knownXvalues *****number\[]***

        (optional) The x-values array. If omitted, the x-values are generated as 1,2,3...n for the number of y-values. X-values may be numeric or of type Year ("YYYY") or YearMonth ("YYYY - MM")

**Return type**

    number

**Examples**

```javascript
// Calculates intercept for a number of given points:
Statistics.intercept([2, 6, 8, 9, 10]) // => 1.3 (Calculates intercept for points 2, 6, 8, 9 and 10)
// Calculates intercept for a number of given points and given x-values:
ROUND(Statistics.intercept([6, 4, 8, 9, 12], [1, 3, 5, 7, 10]), 5) // => 3.72951 (Calculates intercept for points (1,2), (3,6), (5,8), (7,9) and (10,12))
```

#### rsq

```javascript
rsq(knownYvalues: number[], knownXvalues?: number[])
```

Returns the square of the Pearson product moment correlation coefficient. If the x-values are omitted, the assumption is that all x-values have corresponding consecutive y-values \[1 .. nr of x-values]. X-values may be numeric or of type Year ("YYYY") or YearMonth ("YYYY-MM")

**Parameters**

    **knownYvalues *****number\[]***

        The array of values on which the calculation is made.

    **knownXvalues *****number\[]***

        (optional) The x-values array. If omitted, the x-values are generated as 1,2,3...n for the number of y-values. X-values may be numeric or of type Year ("YYYY") or YearMonth ("YYYY - MM")

**Return type**

    number

**Examples**

```javascript
// Calculates rsq for a number of given points:
Statistics.rsq([2, 6, 8, 9, 10]) // => 0.9025 (Calculates rsq for points 2, 6, 8, 9 and 10)
// Calculates rsq for a number of given points and given x-values:
ROUND(Statistics.rsq([2, 6, 8, 9, 10], [1, 3, 5, 7, 10]), 5) // => 0.86117 (Calculates rsq for points (1,2), (3,6), (5,8), (7,9) and (10,10))
```

#### varP

```javascript
varP(values: number[])
```

Calculates variance based on the entire population and assumes that its arguments are the entire population. If your data represents a sample of the population, then compute the variance by using VarS.

**Parameters**

    **values *****number\[]***

        The array of values on which the calculation is made.

**Return type**

    number

**Examples**

```javascript
// Calculates the variance for a number of given points, based on the entire population:
Statistics.varP([1, 2, 3, 4, 5, 6, 7, 8, 9, 25]) // => 42
```

#### varS

```javascript
varS(values: number[])
```

Calculates variance based on a sample and assumes that its arguments are a sample of the population. If your data represents the entire population, then compute the variance by using VarP.

**Parameters**

    **values *****number\[]***

        The array of values on which the calculation is made.

**Return type**

    number

**Examples**

```javascript
// Calculates the variance for a number of given points, based on a sample:
Statistics.varS([1, 2, 3, 4, 5, 6, 7, 8, 9, 25]) // => 46.6667
```

#### stdDevP

```javascript
stdDevP(values: number[])
```

Returns the standard deviation based on the entire population given as arguments.

**Parameters**

    **values *****number\[]***

        The array of values on which the calculation is made.

**Return type**

    number

**Examples**

```javascript
// Calculates standard deviation for a number of given values (which is representing the entire population):
Statistics.stdDevP([1, 2, 3, 4, 5, 6, 7, 8, 9, 25]) // => 6.480740698 (Calculates stdDevP for points 1, 2, 3, 4, 5, 6, 7, 8, 9 and 25)
```

#### stdDevS

```javascript
stdDevS(values: number[])
```

Returns the standard deviation based on a sample list of values.

**Parameters**

    **values *****number\[]***

        The array of values on which the calculation is made.

**Return type**

    number

**Examples**

```javascript
// Calculates standard deviation for a number of given values (which is representing a sample of the entire population):
Statistics.stdDevS([1, 2, 3, 4, 5, 6, 7, 8, 9, 25]) // => 6.831300511 (Calculates stdDevS for points 1, 2, 3, 4, 5, 6, 7, 8, 9 and 25)
```

#### stdErrorP

```javascript
stdErrorP(values: number[])
```

Returns the standard error based on the entire population given as arguments.

**Parameters**

    **values *****number\[]***

        The array of values on which the calculation is made.

**Return type**

    number

**Examples**

```javascript
// Calculates the standard error for a number of given values (which is representing the entire population):
Statistics.stdErrorP([1, 2, 3, 4, 5, 6, 7, 8, 9, 25]) // => 2.049390153 
```

#### stdErrorS

```javascript
stdErrorS(values: number[])
```

Returns the standard error based on a sample list of values.

**Parameters**

    **values *****number\[]***

        The array of values on which the calculation is made.

**Return type**

    number

**Examples**

```javascript
// Calculates standard error for a number of given values (which is representing a sample of the entire population):
Statistics.stdErrorS([1, 2, 3, 4, 5, 6, 7, 8, 9, 25]) // => 2,27710017 
```

#### normalRandom

```javascript
normalRandom(mean: number, stdDev: number)
```

Returns a random number from a normal distribution.

**Parameters**

    **mean *****number***

        The mean or expectation of the distribution.

    **stdDev *****number***

        The standard deviation of the distribution.

**Return type**

    number

**Examples**

```javascript
// Calculates a random number from a normal distribution:
Statistics.normalRandom(0.5, 0.125) // => a random number between 0 and 1 
```

#### normalDistribution

```javascript
normalDistribution(mean: number, stdDev: number, nrOfValues: number)
```

Returns \[nrOfValues] random numbers from a normal distribution.

**Parameters**

    **mean *****number***

        The mean or expectation of the distribution.

    **stdDev *****number***

        The standard deviation of the distribution.

    **nrOfValues *****number***

        The number of random numbers returned.

**Return type**

    number\[]

**Examples**

```javascript
// Generates an array of random numbers from a normal distribution and then calculates the mean
Statistics.mean(Statistics.normalDistribution(0.5, 0.125, 1000000)) // => ~ 0.5 
```

#### gammaRandom

```javascript
gammaRandom(alpha: number, beta: number)
```

Returns a random number from a gamma distribution.

**Parameters**

    **alpha *****number***

        The shape of the distribution. Should be a positive number.

    **beta *****number***

        The rate of the distribution. Should be a positive integer value.

**Return type**

    number

**Examples**

```javascript
// Calculates a random number from a gamma distribution:
Statistics.gammaRandom(2, 2) 
```

#### gammaDistribution

```javascript
gammaDistribution(alpha: number, beta: number, nrOfValues: number)
```

Returns \[nrOfValues] random numbers from a gamma distribution.

**Parameters**

    **alpha *****number***

        The shape of the distribution. Should be a positive number.

    **beta *****number***

        The rate of the distribution. Should be a positive integer value.

    **nrOfValues *****number***

        The number of random numbers returned.

**Return type**

    number\[]

**Examples**

```javascript
// Generates an array of random numbers from a gamma distribution and then calculates the mean
Statistics.mean(Statistics.gammaDistribution(2, 4, 1000000)) // => ~ 0.5 
```

#### meanAbsDev

```javascript
meanAbsDev(values: number[])
```

Returns the Mean Absolute Deviation.

**Parameters**

    **values *****number\[]***

        The array of values on which the calculation is made.

**Return type**

    number

**Examples**

```javascript
// Calculates mean absolute deviation for a number of given values:
Statistics.meanAbsDev([1, 2, 3, 4, 5, 6, 7, 8, 9, 25]) // => 4.2 
```

#### medianAbsDev

```javascript
medianAbsDev(values: number[])
```

Returns the Median Absolute Deviation.

**Parameters**

    **values *****number\[]***

        The array of values on which the calculation is made.

**Return type**

    number

**Examples**

```javascript
// Calculates median absolute deviation for a number of given values:
Statistics.medianAbsDev([1, 2, 3, 4, 5, 6, 7, 8, 9, 25]) // => 2.5 
```

#### findGaps

```javascript
findGaps(values: T[])
```

Returns missing values in an array. Values could be of type number or YearMonth strings

**Parameters**

    **values *****T\[]***

        The array of values in which we look for missing values.

**Return type**

    T\[]

**Examples**

```javascript
// Find missing values in Integer array:
Statistics.findGaps([1, 2, 3, 6, 8]) // => [4, 5, 7] 
// Find missing values in YearMonth array:
Statistics.findGaps(["2019-01", "2019-03", "2019-05", "2019-07", "2019-09"]) // => ["2019-02", "2019-04", "2019-06", "2019-08"]
```

#### fillGaps

```javascript
fillGaps(values: T[])
```

Adds the missing values to an array. Values could be of type number or YearMonth strings

**Parameters**

    **values *****T\[]***

        The array of values in which we look for missing values.

**Return type**

    T\[]

**Examples**

```javascript
// Add missing values to Integer array:
Statistics.fillGaps([1, 2, 3, 6, 8]) // => [1, 2, 3, 4, 5, 6, 7, 8] 
// Add missing values to YearMonth array:
Statistics.fillGaps(["2019-01", "2019-03", "2019-06"]) // => ["2019-01", "2019-02", "2019-03", "2019-04", "2019-05", "2019-06"]
```

#### percentile

```javascript
percentile(values: number[], percentile: number)
```

Returns the value at the given percentile in a sorted array.

**Parameters**

    **values *****number\[]***

        The array of values. Must be sorted.

    **percentile *****number***

        The percentile to find the value for. Must be a number between 0 and 1.

**Return type**

    number

**Examples**

```javascript
// Calculate the 50th percentile of a list of numbers:
Statistics.percentile([1, 2, 3, 4, 5, 6, 7, 8, 9, 25], 0.5) // => 5.5
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.rulecube.com/v2.5/language-reference/statistics.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.