gleam_community/maths/metrics

Metrics: A module offering functions for calculating distances and other types of metrics.

• Distances
• Basic statistical measures

Functions

euclidean_distance

</>
pub fn euclidean_distance(
xarr: List(Float),
yarr: List(Float),
) -> Result(Float, String)

Calculcate the Euclidean distance between two lists (representing vectors):

$\left( \sum_{i=1}^n \left|x_i - y_i \right|^{2} \right)^{\frac{1}{2}}$

In the formula, $$n$$ is the length of the two lists and $$x_i, y_i$$ are the values in the respective input lists indexed by $$i, j$$.

Example:
import gleeunit/should
import gleam_community/maths/elementary
import gleam_community/maths/metrics
import gleam_community/maths/predicates

pub fn example () {
let assert Ok(tol) = elementary.power(-10.0, -6.0)

// Empty lists returns 0.0
metrics.euclidean_distance([], [])
|> should.equal(Ok(0.0))

// Differing lengths returns error
metrics.euclidean_distance([], [1.0])
|> should.be_error()

let assert Ok(result) = metrics.euclidean_distance([0.0, 0.0], [1.0, 2.0])
result
|> predicates.is_close(2.23606797749979, 0.0, tol)
|> should.be_true()
}


manhatten_distance

</>
pub fn manhatten_distance(
xarr: List(Float),
yarr: List(Float),
) -> Result(Float, String)

Calculcate the Manhatten distance between two lists (representing vectors):

$\sum_{i=1}^n \left|x_i - y_i \right|$

In the formula, $$n$$ is the length of the two lists and $$x_i, y_i$$ are the values in the respective input lists indexed by $$i, j$$.

Example:
import gleeunit/should
import gleam_community/maths/elementary
import gleam_community/maths/metrics
import gleam_community/maths/predicates

pub fn example () {
let assert Ok(tol) = elementary.power(-10.0, -6.0)

// Empty lists returns 0.0
metrics.float_manhatten_distance([], [])
|> should.equal(Ok(0.0))

// Differing lengths returns error
metrics.manhatten_distance([], [1.0])
|> should.be_error()

let assert Ok(result) = metrics.manhatten_distance([0.0, 0.0], [1.0, 2.0])
result
|> predicates.is_close(3.0, 0.0, tol)
|> should.be_true()
}


mean

</>
pub fn mean(arr: List(Float)) -> Result(Float, String)

Calculcate the arithmetic mean of the elements in a list:

$\bar{x} = \frac{1}{n}\sum_{i=1}^n x_i$

In the formula, $$n$$ is the sample size (the length of the list) and $$x_i$$ is the sample point in the input list indexed by $$i$$.

Example:
import gleeunit/should
import gleam_community/maths/metrics

pub fn example () {
// An empty list returns an error
[]
|> metrics.mean()
|> should.be_error()

// Valid input returns a result
[1., 2., 3.]
|> metrics.mean()
|> should.equal(Ok(2.))
}


median

</>
pub fn median(arr: List(Float)) -> Result(Float, Nil)

Calculcate the median of the elements in a list.

Example:
import gleeunit/should
import gleam_community/maths/metrics

pub fn example () {
// An empty list returns an error
[]
|> metrics.median()
|> should.be_error()

// Valid input returns a result
[1., 2., 3.]
|> metrics.median()
|> should.equal(Ok(2.))

[1., 2., 3., 4.]
|> metrics.median()
|> should.equal(Ok(2.5))
}


minkowski_distance

</>
pub fn minkowski_distance(
xarr: List(Float),
yarr: List(Float),
p: Float,
) -> Result(Float, String)

Calculcate the Minkowski distance between two lists (representing vectors):

$\left( \sum_{i=1}^n \left|x_i - y_i \right|^{p} \right)^{\frac{1}{p}}$

In the formula, $$p >= 1$$ is the order, $$n$$ is the length of the two lists and $$x_i, y_i$$ are the values in the respective input lists indexed by $$i, j$$.

The Minkowski distance is a generalization of both the Euclidean distance ($$p=2$$) and the Manhattan distance ($$p = 1$$).

Example:
import gleeunit/should
import gleam_community/maths/elementary
import gleam_community/maths/metrics
import gleam_community/maths/predicates

pub fn example () {
let assert Ok(tol) = elementary.power(-10.0, -6.0)

// Empty lists returns 0.0
metrics.minkowski_distance([], [], 1.0)
|> should.equal(Ok(0.0))

// Differing lengths returns error
metrics.minkowski_distance([], [1.0], 1.0)
|> should.be_error()

// Test order < 1
metrics.minkowski_distance([0.0, 0.0], [0.0, 0.0], -1.0)
|> should.be_error()

let assert Ok(result) = metrics.minkowski_distance([0.0, 0.0], [1.0, 2.0], 1.0)
result
|> predicates.is_close(3.0, 0.0, tol)
|> should.be_true()
}


norm

</>
pub fn norm(arr: List(Float), p: Float) -> Float

Calculcate the $$p$$-norm of a list (representing a vector):

$\left( \sum_{i=1}^n \left|x_i\right|^{p} \right)^{\frac{1}{p}}$

In the formula, $$n$$ is the length of the list and $$x_i$$ is the value in the input list indexed by $$i$$.

Example:
import gleeunit/should
import gleam_community/maths/elementary
import gleam_community/maths/metrics
import gleam_community/maths/predicates

pub fn example () {
let assert Ok(tol) = elementary.power(-10.0, -6.0)

[1.0, 1.0, 1.0]
|> metrics.norm(1.0)
|> predicates.is_close(3.0, 0.0, tol)
|> should.be_true()

[1.0, 1.0, 1.0]
|> metrics.norm(-1.0)
|> predicates.is_close(0.3333333333333333, 0.0, tol)
|> should.be_true()
}


standard_deviation

</>
pub fn standard_deviation(
arr: List(Float),
ddof: Int,
) -> Result(Float, String)

Calculcate the sample standard deviation of the elements in a list: $s = \left(\frac{1}{n - d} \sum_{i=1}^{n}(x_i - \bar{x})\right)^{\frac{1}{2}}$

In the formula, $$n$$ is the sample size (the length of the list) and $$x_i$$ is the sample point in the input list indexed by $$i$$. Furthermore, $$\bar{x}$$ is the sample mean and $$d$$ is the “Delta Degrees of Freedom”, and is by default set to $$d = 0$$, which gives a biased estimate of the sample standard deviation. Setting $$d = 1$$ gives an unbiased estimate.

Example:
import gleeunit/should
import gleam_community/maths/metrics

pub fn example () {
// Degrees of freedom
let ddof: Int = 1

// An empty list returns an error
[]
|> metrics.standard_deviationddof)
|> should.be_error()

// Valid input returns a result
[1., 2., 3.]
|> metrics.standard_deviation(ddof)
|> should.equal(Ok(1.))
}


variance

</>
pub fn variance(
arr: List(Float),
ddof: Int,
) -> Result(Float, String)

Calculcate the sample variance of the elements in a list: $s^{2} = \frac{1}{n - d} \sum_{i=1}^{n}(x_i - \bar{x})$

In the formula, $$n$$ is the sample size (the length of the list) and $$x_i$$ is the sample point in the input list indexed by $$i$$. Furthermore, $$\bar{x}$$ is the sample mean and $$d$$ is the “Delta Degrees of Freedom”, and is by default set to $$d = 0$$, which gives a biased estimate of the sample variance. Setting $$d = 1$$ gives an unbiased estimate.

Example:
import gleeunit/should
import gleam_community/maths/metrics

pub fn example () {
// Degrees of freedom
let ddof: Int = 1

// An empty list returns an error
[]
|> metrics.variance(ddof)
|> should.be_error()

// Valid input returns a result
[1., 2., 3.]
|> metrics.variance(ddof)
|> should.equal(Ok(1.))
}