milia.recommend.ranker#

Learning to rank: order items within each list by a score learned from their features.

A ranker is trained on lists whose items carry a known outcome, such as the transformers of a network with their simulated violation hours, and learns a score whose order within each list matches the order of the outcome. Ranker uses LambdaMART [Burges, 2010], gradient-boosted trees trained with the LambdaRank gradient, which weights each swap of two items by the change in NDCG it causes (milia.evaluate.ranking.ndcg()), so that errors near the top of a list cost most.

LambdaMART needs integer relevance grades. A continuous outcome is graded within each list into levels quantile grades, from 0 for the least to levels - 1 for the most relevant; the grading depends only on the order of the outcome within its list, so lists on different scales can be learned together.

LightGBM is an optional dependency, installed with pip install pundamilia[ranking].

Functions

grades(outcome, groups[, levels])

Quantile grades of an outcome within each list, from 0 (least) to levels - 1 (most relevant).

Classes

Ranker([levels, estimators, rate, leaves, ...])

LambdaMART ranker over lists of items, trained on a continuous outcome graded within each list.

milia.recommend.ranker.grades(outcome, groups, levels=5)#

Quantile grades of an outcome within each list, from 0 (least) to levels - 1 (most relevant).

Parameters:
  • outcome (ArrayLike) – Outcome of each item, higher is more relevant.

  • groups (ArrayLike) – List of each item.

  • levels (int) – Number of grades.

Return type:

ndarray

Returns:

The integer grade of each item.

Examples

>>> grades([1.0, 5.0, 3.0, 10.0, 20.0, 30.0], [0, 0, 0, 1, 1, 1], levels=3).tolist()
[0, 2, 1, 0, 1, 2]
class milia.recommend.ranker.Ranker(levels=5, estimators=200, rate=0.05, leaves=15, minimum=5, seed=0)#

Bases: BaseEstimator

LambdaMART ranker over lists of items, trained on a continuous outcome graded within each list.

Parameters:
  • levels (int) – Quantile grades of the outcome within each list.

  • estimators (int) – Boosted trees.

  • rate (float) – Learning rate.

  • leaves (int) – Leaves per tree.

  • minimum (int) – Minimum items in a leaf.

  • seed (int) – Random seed.

Examples

>>> import numpy as np
>>> rng = np.random.default_rng(0)
>>> X = rng.normal(size=(200, 3))
>>> groups = np.repeat(np.arange(10), 20)
>>> outcome = X[:, 0] + 0.1 * rng.normal(size=200)
>>> ranker = Ranker(estimators=50).fit(X, outcome, groups)
>>> from milia.evaluate.ranking import kendall
>>> kendall(outcome, ranker.predict(X), groups) > 0.8
True
fit(X, y, groups)#

Learn a score that orders the items of each list as their outcome does.

Parameters:
  • X (ArrayLike) – Features of each item.

  • y (ArrayLike) – Outcome of each item, higher is more relevant.

  • groups (ArrayLike) – List of each item; items of one list need not be contiguous.

Return type:

Ranker

Returns:

The fitted ranker.

Raises:

ImportError – If LightGBM is not installed.

predict(X)#

Ranking score of each item; only its order within a list is meaningful.

Parameters:

X (ArrayLike) – Features of each item.

Return type:

ndarray

Returns:

The score of each item, higher ranked first.

set_fit_request(*, groups='$UNCHANGED$')#

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

  • True: metadata is requested, and passed to fit if provided. The request is ignored if metadata is not provided.

  • False: metadata is not requested and the meta-estimator will not pass it to fit.

  • None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

  • str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters#

groupsstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for groups parameter in fit.

Returns#

selfobject

The updated object.

Return type:

Ranker