README.md

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}
}

Footnotes

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. ↩