gleam_community_maths - v1.1.0

gleam_community/maths/metrics

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

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, String)

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.))
}
✨ Search Document