milia.recommend.ranking#

Ranking cases, groups and models, with uncertainty on the ranks.

weights() is the single diversity weighting used everywhere a ranking combines several metrics (cluster-count selection and model comparison alike): a metric that mostly repeats others gets less weight.

Module Attributes

LOWER

Metric names treated as lower-is-better by models().

Functions

combine(frame, columns[, method])

Combine columns on different scales: min-max each, then take the max or the mean.

groups(frame, by, agg[, score])

Aggregate cases to groups (e.g. buses, feeders), combine the aggregates and rank the groups.

interval(frame, score[, ascending, ...])

rank() plus a bootstrap interval on each rank.

models(scores[, lower])

Diversity-weighted multi-metric ranking of models.

rank(frame, score[, ascending])

Sort by a score column and prepend a rank column (1 = top).

weights(scores)

Diversity weights of metric columns from their mean absolute Spearman correlation.

milia.recommend.ranking.weights(scores)#

Diversity weights of metric columns from their mean absolute Spearman correlation.

Each metric’s weight is one minus its mean absolute correlation with the others, floored at 0.05 and normalised to sum to one, so a metric that mostly repeats others counts less.

Parameters:

scores (DataFrame) – One column per metric, oriented higher-is-better, one row per candidate.

Return type:

ndarray

Returns:

One weight per column.

Examples

>>> import pandas as pd
>>> scores = pd.DataFrame({"a": [1, 2, 3], "b": [1, 2, 3], "c": [3, 1, 2]})
>>> weights(scores).round(2).tolist()
[0.3, 0.3, 0.4]
milia.recommend.ranking.combine(frame, columns, method='max')#

Combine columns on different scales: min-max each, then take the max or the mean.

Parameters:
  • frame (DataFrame) – One row per case.

  • columns (list[str]) – Columns combined.

  • method (str) – "max" (a case is as risky as its worst dimension) or "mean".

Return type:

Series

Returns:

One combined score per row, on [0, 1].

Raises:

ValueError – If the method is unknown.

Examples

>>> import pandas as pd
>>> combine(pd.DataFrame({"v": [1.0, 3.0], "w": [10.0, 0.0]}), ["v", "w"]).tolist()
[1.0, 1.0]
milia.recommend.ranking.rank(frame, score, ascending=False)#

Sort by a score column and prepend a rank column (1 = top).

Parameters:
  • frame (DataFrame) – One row per case.

  • score (str) – Column ranked on.

  • ascending (bool) – Rank the lowest score first.

Return type:

DataFrame

Returns:

The sorted frame with rank.

Examples

>>> import pandas as pd
>>> rank(pd.DataFrame({"name": ["a", "b"], "s": [1.0, 2.0]}), "s")["name"].tolist()
['b', 'a']
milia.recommend.ranking.interval(frame, score, ascending=False, bootstrap=200, random_state=0)#

rank() plus a bootstrap interval on each rank.

The cases are resampled with replacement and re-ranked; the 5th and 95th percentiles of each case’s positions give lower and upper. Wide intervals mean the order among those cases is not settled.

Parameters:
  • frame (DataFrame) – One row per case.

  • score (str) – Column ranked on.

  • ascending (bool) – Rank the lowest score first.

  • bootstrap (int) – Resamples.

  • random_state (int) – Seed.

Return type:

DataFrame

Returns:

The ranked frame with lower and upper.

Examples

>>> import pandas as pd
>>> ranked = interval(pd.DataFrame({"s": [1.0, 2.0, 3.0]}), "s", bootstrap=50)
>>> bool((ranked["lower"] <= ranked["rank"]).all())
True
milia.recommend.ranking.groups(frame, by, agg, score=None)#

Aggregate cases to groups (e.g. buses, feeders), combine the aggregates and rank the groups.

Parameters:
  • frame (DataFrame) – One row per case.

  • by (str) – Grouping column.

  • agg (dict[str, str]) – Column to aggregation, e.g. {"vmax": "max", "kw": "mean"}.

  • score (Iterable[str] | None) – Aggregated columns to combine into score; all of agg by default.

Return type:

DataFrame

Returns:

One row per group with the aggregates, score and rank.

Examples

>>> import pandas as pd
>>> frame = pd.DataFrame({"bus": [1, 1, 2], "v": [1.0, 1.2, 1.05]})
>>> groups(frame, "bus", {"v": "max"})["bus"].tolist()
[1, 2]
milia.recommend.ranking.LOWER = frozenset({'mae', 'mape', 'mse', 'nrmse', 'rmse', 'smape', 'wmape'})#

Metric names treated as lower-is-better by models().

milia.recommend.ranking.models(scores, lower=None)#

Diversity-weighted multi-metric ranking of models.

Metrics named in lower are negated so higher is better throughout; each metric is ranked across models and combined three ways: mean rank, Borda count, and Borda weighted by weights().

Parameters:
  • scores (DataFrame) – One row per model, one column per metric.

  • lower (Iterable[str] | None) – Lower-is-better metric names; LOWER by default.

Return type:

DataFrame

Returns:

scores with mean, borda and weighted, best first; the weights are in attrs["weights"].

Examples

>>> import pandas as pd
>>> scores = pd.DataFrame({"mae": [1.0, 2.0], "corr": [0.9, 0.5]}, index=["knn", "mean"])
>>> models(scores).index.tolist()
['knn', 'mean']