# gizai:ml/rank

rank fusion and retrieval metrics.

```gizlang
import * as Rank from "gizai:ml/rank";
```

## Types

### `Fused`

```gizlang
type Fused = { id: string; score: f64; }
```

An item of a fused ranking and its score.

- `id`: `string`
- `score`: `f64`

## Functions

### `rrf`

```gizlang
function rrf(ranks: Vec<f64>, k: f64): f64
```

The reciprocal rank fusion score of one item: the sum of 1 / (k + rank) over the lists that ranked it, each rank
from 1; a rank under 1 is a list that did not rank it. It divides first, so a large k or rank does not overflow.

Effects: fail.

### `fuse`

```gizlang
function fuse(lists: Vec<Vec<string>>, weights: Vec<f64>, k: f64): Vec<Fused>
```

The fusion of ranked lists of ids (text; the best first), as hybrid search joins a text ranking and a vector ranking:
each id's weighted reciprocal rank sum, weights[i] times 1 / (k + rank) in list i (an empty `weights`: all 1). The
result is by score, the higher first; equal scores keep the order in which the ids first come. A repeated id in a
list counts at its first rank.

Effects: fail.

### `recallAt`

```gizlang
function recallAt(ranked: Vec<string>, relevant: Vec<string>, k: i64): f64
```

Recall at k: the share of the relevant ids in the first k ranked (k 0: all); 0 with no relevant id.

Effects: fail.

### `precisionAt`

```gizlang
function precisionAt(ranked: Vec<string>, relevant: Vec<string>, k: i64): f64
```

Precision at k: the share of the first k places (k 0: all ranked) that hold a relevant id.

Effects: fail.

### `reciprocalRank`

```gizlang
function reciprocalRank(ranked: Vec<string>, relevant: Vec<string>, k: i64): f64
```

The reciprocal rank: 1 / the place of the first relevant id in the first k (k 0: all); 0 when none is there. Its
mean over queries is MRR.

Effects: fail.

### `averagePrecision`

```gizlang
function averagePrecision(ranked: Vec<string>, relevant: Vec<string>, k: i64): f64
```

The average precision in the first k (k 0: all), as trec_eval's map: the precision at each place of a relevant id,
summed and divided by the count of relevant ids.

Effects: fail.

### `ndcgAt`

```gizlang
function ndcgAt(ranked: Vec<string>, relevant: Vec<string>, gains: Vec<f64>, k: i64): f64
```

The normalized discounted cumulative gain at k (k 0: all), as trec_eval's ndcg_cut: the sum of gain / log2(place
+ 1) over the first k ranked, divided by that of the ideal order. `gains[i]` is the graded relevance of
`relevant[i]`; with no gains each relevant id has gain 1. 0 when the ideal gain is 0.

Effects: fail.