v2026.11.2
All Bundles
Bundle

Verification metrics for a system that decides whether two things match: a face or voice verifier, a signature checker, a duplicate detector. The input is one similarity score per pair (higher means more alike) and a label per pair, true when the two really are the same (a genuine pair) and false when they are not (an impostor pair).

A pair is accepted when its score is greater than or equal to the threshold. Three rates describe a threshold: - FAR, the false acceptance rate: impostor pairs accepted, divided by impostor pairs. - FRR, the false rejection rate: genuine pairs rejected, divided by genuine pairs. - accuracy: pairs decided correctly, divided by all pairs. Raising the threshold lowers FAR and raises FRR. The equal error rate (EER) is the value where the two are equal.

The curve. Verification->Evaluate sorts the distinct scores v0 < v1 < ... < v(k-1) and reports one operating point per threshold v(j), then a last point at +Infinity that accepts nothing (FAR 0, FRR 1). The first point (threshold v0) accepts everything (FAR 1, FRR 0). So there are k + 1 points, thresholds ascending, FAR never increasing and FRR never decreasing. Pairs that share a score share a point, so a tie is never split.

The EER and its interpolation rule. Let d(j) = FAR(j) - FRR(j); d is 1 at the first point and -1 at the last, and never increases. The EER is read at the first point j with d(j) <= 0. When d(j) is 0 the EER is FAR(j) and the threshold is v(j). Otherwise the two rates cross between point j-1 and point j, and both the EER and the threshold are linearly interpolated along that segment at lambda = d(j-1) / (d(j-1) - d(j)): EER = FAR(j-1) + lambda * (FAR(j) - FAR(j-1)), threshold = v(j-1) + lambda * (v(j) - v(j-1)). When the crossing lies after the highest score (the segment ends at +Infinity) the threshold reported is the highest score, and the EER is still interpolated. The same rule is what scipy's interp1d over a ROC curve gives, which is how the regression test checks it.

No call here ends the program on bad input. Evaluate returns a result whose IsValid() is false and whose GetError() says why (a size mismatch, an empty input, a NaN or infinite score, no genuine pair or no impostor pair); every number in it is then NaN. The single-number functions return NaN for the same input; call Verification->Check to read the reason. GetError() is "" when there is nothing to report. Needs only gen_collect: compile with -lib ml_verify,gen_collect.

Similarity

Similarity between two vectors, for embeddings. No call ends the program on bad input; each returns NaN or Nil.

Operations

Cosine # function

Cosine similarity of two vectors, in -1 to 1.

function : Cosine(a:Float[], b:Float[]) ~ Float

Parameters

NameTypeDescription
aFloatfirst vector
bFloatsecond vector

Return

TypeDescription
Floatthe cosine, or NaN when a vector is Nil or empty, the lengths differ, a value is not finite or a vector has no length (all zeros)

Normalize # function

A copy of a vector scaled to length 1, so the dot product of two of them is their cosine.

function : Normalize(v:Float[]) ~ Float[]

Parameters

NameTypeDescription
vFloatthe vector

Return

TypeDescription
Floatthe unit vector, or Nil when the vector is Nil, empty, not finite or all zeros

NotFinite # function

True for NaN, +Infinity and -Infinity.

function : NotFinite(v:Float) ~ Bool

Parameters

NameTypeDescription
vFloatthe number

Return

TypeDescription
Booltrue when the number is not finite