metric

README

metric

Docs: GoDoc

metric provides various similarity / distance metrics for comparing floating-point vectors. All functions have 32 and 64 bit variants, and skip NaN's (often used for missing) and will panic if the lengths of the two slices are unequal (no error return).

The signatures of all such metric functions are identical, captured as types: metric.Func32 and metric.Func64 so that other functions that use a metric can take a pointer to any such function.

Documentation

Overview

Package metric provides various similarity / distance metrics for comparing floating-point vectors. All functions have 32 and 64 bit variants, and skip NaN's (often used for missing) and will panic if the lengths of the two slices are unequal (no error return).

The signatures of all such metric functions are identical, captured as types: metric.Func32 and metric.Func64 so that other functions that use a metric can take a pointer to any such function.

Index

• Variables
• func Abs32(a, b []float32) float32
• func Abs64(a, b []float64) float64
• func ClosestRow32(probe *etensor.Float32, col *etensor.Float32, mfun Func32) (int, float32)
• func ClosestRow32Py(probe *etensor.Float32, col *etensor.Float32, std StdMetrics) []float32
• func ClosestRow64(probe etensor.Tensor, col etensor.Tensor, mfun Func64) (int, float64)
• func ClosestRow64Py(probe etensor.Tensor, col etensor.Tensor, std StdMetrics) []float64
• func Correlation32(a, b []float32) float32
• func Correlation64(a, b []float64) float64
• func Cosine32(a, b []float32) float32
• func Cosine64(a, b []float64) float64
• func Covariance32(a, b []float32) float32
• func Covariance64(a, b []float64) float64
• func CrossEntropy32(a, b []float32) float32
• func CrossEntropy64(a, b []float64) float64
• func Euclidean32(a, b []float32) float32
• func Euclidean64(a, b []float64) float64
• func EuclideanBinTol32(a, b []float32) float32
• func EuclideanBinTol64(a, b []float64) float64
• func Hamming32(a, b []float32) float32
• func Hamming64(a, b []float64) float64
• func Increasing(std StdMetrics) bool
• func InnerProduct32(a, b []float32) float32
• func InnerProduct64(a, b []float64) float64
• func InvCorrelation32(a, b []float32) float32
• func InvCorrelation64(a, b []float64) float64
• func InvCosine32(a, b []float32) float32
• func InvCosine64(a, b []float64) float64
• func SumSquares32(a, b []float32) float32
• func SumSquares64(a, b []float64) float64
• func SumSquaresBinTol32(a, b []float32) float32
• func SumSquaresBinTol64(a, b []float64) float64
• func Tolerance32(a, b []float32, tol float32)
• func Tolerance64(a, b []float64, tol float64)
• type Func32
  • func StdFunc32(std StdMetrics) Func32
• type Func64
  • func StdFunc64(std StdMetrics) Func64
• type StdMetrics
  • func (i *StdMetrics) FromString(s string) error
  • func (ev StdMetrics) MarshalJSON() ([]byte, error)
  • func (i StdMetrics) String() string
  • func (ev *StdMetrics) UnmarshalJSON(b []byte) error

Variables

var KiT_StdMetrics = kit.Enums.AddEnum(StdMetricsN, kit.NotBitFlag, nil)

Functions

func Abs32

func Abs32(a, b []float32) float32

Abs32 computes the sum of absolute value of differences (L1 Norm). Skips NaN's and panics if lengths are not equal.

func Abs64

func Abs64(a, b []float64) float64

Abs64 computes the sum of absolute value of differences (L1 Norm). Skips NaN's and panics if lengths are not equal.

func ClosestRow32

func ClosestRow32(probe *etensor.Float32, col *etensor.Float32, mfun Func32) (int, float32)

ClosestRow32 returns the closest fit between probe pattern and patterns in an etensor.Float32 where the outer-most dimension is assumed to be a row (e.g., as a column in an etable), using the given metric function, *which must have the Increasing property* -- i.e., larger = further. returns the row and metric value for that row. Col cell sizes must match size of probe (panics if not).

func ClosestRow32Py

func ClosestRow32Py(probe *etensor.Float32, col *etensor.Float32, std StdMetrics) []float32

ClosestRow32Py returns the closest fit between probe pattern and patterns in an etensor.Float32 where the outer-most dimension is assumed to be a row (e.g., as a column in an etable), using the given metric function, *which must have the Increasing property* -- i.e., larger = further. returns the row and metric value for that row. Col cell sizes must match size of probe (panics if not). Py version is for Python, returns a slice with row, cor, takes std metric

func ClosestRow64

func ClosestRow64(probe etensor.Tensor, col etensor.Tensor, mfun Func64) (int, float64)

ClosestRow64 returns the closest fit between probe pattern and patterns in an etensor.Tensor where the outer-most dimension is assumed to be a row (e.g., as a column in an etable), using the given metric function, *which must have the Increasing property* -- i.e., larger = further. returns the row and metric value for that row. Col cell sizes must match size of probe (panics if not). Optimized for etensor.Float64 but works for any tensor.

func ClosestRow64Py

func ClosestRow64Py(probe etensor.Tensor, col etensor.Tensor, std StdMetrics) []float64

ClosestRow64Py returns the closest fit between probe pattern and patterns in an etensor.Tensor where the outer-most dimension is assumed to be a row (e.g., as a column in an etable), using the given metric function, *which must have the Increasing property* -- i.e., larger = further. returns the row and metric value for that row. Col cell sizes must match size of probe (panics if not). Optimized for etensor.Float64 but works for any tensor. Py version is for Python, returns a slice with row, cor, takes std metric

func Correlation32

func Correlation32(a, b []float32) float32

Correlation32 computes the vector similarity in range (-1..1) as the mean of the co-product of each vector element minus the mean of that vector, normalized by the product of their standard deviations: cor(A,B) = E[(A - E(A))(B - E(B))] / sigma(A) sigma(B). (i.e., the standardized covariance) -- equivalent to the cosine of mean-normalized vectors. Skips NaN's and panics if lengths are not equal.

func Correlation64

func Correlation64(a, b []float64) float64

Correlation64 computes the vector similarity in range (-1..1) as the mean of the co-product of each vector element minus the mean of that vector, normalized by the product of their standard deviations: cor(A,B) = E[(A - E(A))(B - E(B))] / sigma(A) sigma(B). (i.e., the standardized covariance) -- equivalent to the cosine of mean-normalized vectors. Skips NaN's and panics if lengths are not equal.

func Cosine32

func Cosine32(a, b []float32) float32

Cosine32 computes the cosine of the angle between two vectors (-1..1), as the normalized inner product: inner product / sqrt(ssA * ssB). If vectors are mean-normalized = Correlation. Skips NaN's and panics if lengths are not equal.

func Cosine64

func Cosine64(a, b []float64) float64

Cosine32 computes the cosine of the angle between two vectors (-1..1), as the normalized inner product: inner product / sqrt(ssA * ssB). If vectors are mean-normalized = Correlation. Skips NaN's and panics if lengths are not equal.

func Covariance32

func Covariance32(a, b []float32) float32

Covariance32 computes the mean of the co-product of each vector element minus the mean of that vector: cov(A,B) = E[(A - E(A))(B - E(B))] Skips NaN's and panics if lengths are not equal.

func Covariance64

func Covariance64(a, b []float64) float64

Covariance64 computes the mean of the co-product of each vector element minus the mean of that vector: cov(A,B) = E[(A - E(A))(B - E(B))] Skips NaN's and panics if lengths are not equal.

func CrossEntropy32

func CrossEntropy32(a, b []float32) float32

CrossEntropy32 computes cross-entropy between the two vectors. Skips NaN's and panics if lengths are not equal.

func CrossEntropy64

func CrossEntropy64(a, b []float64) float64

CrossEntropy64 computes the cross-entropy between the two vectors. Skips NaN's and panics if lengths are not equal.

func Euclidean32

func Euclidean32(a, b []float32) float32

Euclidean32 computes the square-root of sum-of-squares distance between two vectors (aka the L2 norm). Skips NaN's and panics if lengths are not equal. Uses optimized algorithm from BLAS that avoids numerical overflow.

func Euclidean64

func Euclidean64(a, b []float64) float64

Euclidean64 computes the square-root of sum-of-squares distance between two vectors (aka the L2 norm). Skips NaN's and panics if lengths are not equal. Uses optimized algorithm from BLAS that avoids numerical overflow.

func EuclideanBinTol32

func EuclideanBinTol32(a, b []float32) float32

EuclideanBinTol32 computes the square-root of sum-of-squares distance between two vectors (aka the L2 norm). Skips NaN's and panics if lengths are not equal. Uses optimized algorithm from BLAS that avoids numerical overflow. BinTol version uses binary tolerance for 0-1 valued-vectors where abs diff < .5 counts as 0 error (i.e., closer than not).

func EuclideanBinTol64

func EuclideanBinTol64(a, b []float64) float64

EuclideanBinTol64 computes the square-root of sum-of-squares distance between two vectors (aka the L2 norm). Skips NaN's and panics if lengths are not equal. Uses optimized algorithm from BLAS that avoids numerical overflow. BinTol version uses binary tolerance for 0-1 valued-vectors where abs diff < .5 counts as 0 error (i.e., closer than not).

func Hamming32

func Hamming32(a, b []float32) float32

Hamming32 computes the sum of 1's for every element that is different (city block). Skips NaN's and panics if lengths are not equal.

func Hamming64

func Hamming64(a, b []float64) float64

Hamming64 computes the sum of absolute value of differences (L1 Norm). Skips NaN's and panics if lengths are not equal.

func Increasing

func Increasing(std StdMetrics) bool

Increasing returns true if the distance metric is such that metric values increase as a function of distance (e.g., Euclidean) and false if metric values decrease as a function of distance (e.g., Cosine, Correlation)

func InnerProduct32

func InnerProduct32(a, b []float32) float32

InnerProduct32 computes the sum of the element-wise product of the two vectors. Skips NaN's and panics if lengths are not equal.

func InnerProduct64

func InnerProduct64(a, b []float64) float64

InnerProduct64 computes the mean of the co-product of each vector element minus the mean of that vector, normalized by the product of their standard deviations: cor(A,B) = E[(A - E(A))(B - E(B))] / sigma(A) sigma(B). (i.e., the standardized covariance) -- equivalent to the cosine of mean-normalized vectors. Skips NaN's and panics if lengths are not equal.

func InvCorrelation32

func InvCorrelation32(a, b []float32) float32

InvCorrelation32 computes 1 - the vector similarity in range (-1..1) as the mean of the co-product of each vector element minus the mean of that vector, normalized by the product of their standard deviations: cor(A,B) = E[(A - E(A))(B - E(B))] / sigma(A) sigma(B). (i.e., the standardized covariance) -- equivalent to the cosine of mean-normalized vectors. Skips NaN's and panics if lengths are not equal.

func InvCorrelation64

func InvCorrelation64(a, b []float64) float64

InvCorrelation64 computes 1 - the vector similarity in range (-1..1) as the mean of the co-product of each vector element minus the mean of that vector, normalized by the product of their standard deviations: cor(A,B) = E[(A - E(A))(B - E(B))] / sigma(A) sigma(B). (i.e., the standardized covariance) -- equivalent to the cosine of mean-normalized vectors. Skips NaN's and panics if lengths are not equal.

func InvCosine32

func InvCosine32(a, b []float32) float32

InvCosine32 computes 1 - cosine of the angle between two vectors (-1..1), as the normalized inner product: inner product / sqrt(ssA * ssB). If vectors are mean-normalized = Correlation. Skips NaN's and panics if lengths are not equal.

func InvCosine64

func InvCosine64(a, b []float64) float64

InvCosine32 computes 1 - cosine of the angle between two vectors (-1..1), as the normalized inner product: inner product / sqrt(ssA * ssB). If vectors are mean-normalized = Correlation. Skips NaN's and panics if lengths are not equal.

func SumSquares32

func SumSquares32(a, b []float32) float32

SumSquares32 computes the sum-of-squares distance between two vectors. Skips NaN's and panics if lengths are not equal. Uses optimized algorithm from BLAS that avoids numerical overflow.

func SumSquares64

func SumSquares64(a, b []float64) float64

SumSquares64 computes the sum-of-squares distance between two vectors. Skips NaN's and panics if lengths are not equal. Uses optimized algorithm from BLAS that avoids numerical overflow.

func SumSquaresBinTol32

func SumSquaresBinTol32(a, b []float32) float32

SumSquaresBinTol32 computes the sum-of-squares distance between two vectors. Skips NaN's and panics if lengths are not equal. Uses optimized algorithm from BLAS that avoids numerical overflow. BinTol version uses binary tolerance for 0-1 valued-vectors where abs diff < .5 counts as 0 error (i.e., closer than not).

func SumSquaresBinTol64

func SumSquaresBinTol64(a, b []float64) float64

SumSquaresBinTol64 computes the sum-of-squares distance between two vectors. Skips NaN's and panics if lengths are not equal. Uses optimized algorithm from BLAS that avoids numerical overflow. BinTol version uses binary tolerance for 0-1 valued-vectors where abs diff < .5 counts as 0 error (i.e., closer than not).

func Tolerance32

func Tolerance32(a, b []float32, tol float32)

Tolerance32 sets a = b for any element where |a-b| <= tol. This can be called prior to any metric function.

func Tolerance64

func Tolerance64(a, b []float64, tol float64)

Tolerance64 sets a = b for any element where |a-b| <= tol. This can be called prior to any metric function.

Types

type Func32

type Func32 func(a, b []float32) float32

Func32 is a distance / similarity metric operating on slices of float32 numbers

func StdFunc32

func StdFunc32(std StdMetrics) Func32

StdFunc32 returns a standard metric function as specified

type Func64

type Func64 func(a, b []float64) float64

Func64 is a distance / similarity metric operating on slices of float64 numbers

func StdFunc64

func StdFunc64(std StdMetrics) Func64

StdFunc64 returns a standard metric function as specified

type StdMetrics

type StdMetrics int

StdMetrics are standard metric functions

const (
	Euclidean StdMetrics = iota
	SumSquares
	Abs
	Hamming

	EuclideanBinTol
	SumSquaresBinTol

	// InvCosine is 1-Cosine -- useful to convert into an Increasing metric
	InvCosine

	// InvCorrelation is 1-Correlation -- useful to convert into an Increasing metric
	InvCorrelation

	CrossEntropy

	// Everything below here is !Increasing -- larger = closer, not farther
	InnerProduct
	Covariance
	Correlation
	Cosine

	StdMetricsN
)

func (*StdMetrics) FromString

func (i *StdMetrics) FromString(s string) error

func (StdMetrics) MarshalJSON

func (ev StdMetrics) MarshalJSON() ([]byte, error)

func (StdMetrics) String

func (i StdMetrics) String() string

func (*StdMetrics) UnmarshalJSON

func (ev *StdMetrics) UnmarshalJSON(b []byte) error