gleam_community_maths - v1.0.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