Crate faasle

faasle

faasle¹ is a Rust package for evaluating distances (metrics) between multidimensional arrays. It is designed to be simple, fast, and easy to use.

Usage

use faasle::{Distance, Euclidean};
use ndarray::{ArrayD, Axis};

let x =
ArrayD::from_shape_vec(vec![2, 4], vec![0.0, 3.0, 3.0, 5.0, 11.0, 2.0, 0.0, 9.0]).unwrap();
let y =
ArrayD::from_shape_vec(vec![2, 4], vec![9.0, 2.0, 2.0, 1.0, 9.0, 5.0, 4.0, 7.0]).unwrap();
let metric = Euclidean::new();
let distance = metric.evaluate( & x, & y, Axis(1)).unwrap();
assert!(distance.abs_diff_eq(
    &ArrayD::from_shape_vec(vec![2], vec![9.9498743710662, 5.744562646538029]).unwrap(),
    1e-6
));

Hierarchy of Types

Mathematically a distance metric is a function $d:\mathcal{X}\times\mathcal{X}\rightarrow\mathbb{R}$, where $\mathcal{X}$ is a set, such that they satisfy the following properties:

Positivity

1. $d(x, y) \geq 0$ for all $x, y \in \mathcal{X}$,
2. $d(x, y) = 0$ if and only if $x = y$,

Symmetry

3. $d(x, y) = d(y, x)$ for all $x, y \in \mathcal{X}$,

Triangle Inequality

4. $d(x, z) \leq d(x, y) + d(y, z)$ for all $x, y, z \in \mathcal{X}$.

The hierarchy of types and their properties are as follows:

	PreMetric	SemiMetric	Metric
Positivity	✅	✅	✅
Symmetry	❌	✅	✅
Triangle Inequality	❌	❌	✅

How to cite?

@software{faaslers2024github,
    author = {{M}eesum {Q}azalbash},
    title = {{faasle}: Rust crate for evaluating distances (metrics).},
    url = {https://github.com/Qazalbash/faasle},
    version = {0.0.1},
    year = {2024}
}

---

1. Faasle is an Urdu word, which means distance in English. It is also the name of the infamous Coke Studio Season 10 song by Quratulain Balouch and Kaavish. ↩

Structs

BhattacharyyaDist

BhattacharyyaDist(x, y) = -ln(sum(sqrt(x .* y)))+0.5*ln(sum(x))+0.5*ln(sum(y))

BrayCurtis

BrayCurtis(x, y) = sum(|x - y|) / sum(|x + y|)

Chebyshev

Chebyshev(x, y) = max(|x - y|)

ChiSqDist

ChiSqDist(x, y) = sum((x - y).^2 ./ (x + y))

Cityblock

Cityblock(x, y) = sum(|x - y|)

Euclidean

Euclidean(x, y) = sqrt(sum((x - y).^2))

GenKLDivergence

GenKLDivergence(x, y) = sum(x .* ln(x ./ y) - x + y)

Hamming

Hamming(x, y) = sum(x!=y)

JSDivergence

JSDivergence(x, y) = KLDivergence(x, (x + y) ./ 2) + KLDivergence(y, (x + y) ./ 2)

KLDivergence

KLDivergence(x, y) = sum(x .* ln(x ./ y))

MeanAbsDeviation

MeanAbsDeviation(x, y) = mean(|x - y|)

MeanSqDeviation

MeanSqDeviation(x, y) = mean((x - y).^2)

Minkowski

Minkowski(x, y) = sum(|x - y|.^p).^(1/p)

RMSDeviation

RMSDeviation(x, y) = sqrt(mean((x - y).^2))

SqEuclidean

SqEuclidean(x, y) = sqrt(sum((x - y).^2))

TotalVariation

TotalVariation(x, y) = sum(|x - y|) ./ 2

Traits

Distance

The Distance trait defines the interface for evaluating distances (metrics) between multidimensional arrays. Implement this trait for a distance metric. The trait provides a method to evaluate the distance between two arrays along a specified axis.