plackett_luce
heterogeneity.plackett_luce
Plackett-Luce models on per-dataset method rankings.
The Bradley-Terry tree works from pairwise wins. When the natural input is a full ranking of the methods per dataset, the Plackett-Luce model (Turner, van Etten, Firth and Kosmidis) is the direct generalisation: it turns each dataset’s ordering of the methods into a single latent strength per method, the worth, with the worths summing to one. On strictly pairwise input it reduces to the Bradley-Terry model, so it is the wider tool for the same question of which method is stronger overall.
For one metric, each dataset column of a method by dataset matrix is read as a ranking of the methods (the higher score ranks first, after orienting by polarity), with ties allowed and missing cells left out of that dataset’s ranking. The model is fit by R’s PlackettLuce in a one-shot subprocess, the same boundary as the other heterogeneity wrappers. Use plackett_luce_available to check the R toolchain before calling plackett_luce.
This is a global ranking tool, not a heterogeneity split: it complements the Bradley-Terry tree (which localises where the ranking reverses) by giving a worth with a reference-free quasi-standard-error per method, so two methods can be compared without picking a baseline.
Classes
| Name | Description |
|---|---|
| PlackettLuceReport | Outcome of a Plackett-Luce fit on per-dataset method rankings. |
PlackettLuceReport
heterogeneity.plackett_luce.PlackettLuceReport(self, method_names, worth, quasi_se, log_worth, n_rankings, connected, npseudo, loglik, df, aic, warnings)
Outcome of a Plackett-Luce fit on per-dataset method rankings.
Attributes
| Name | Type | Description |
|---|---|---|
| method_names | tuple[str, …] | Method labels, the order the arrays are aligned to (the input order). |
| worth | np.ndarray | Worth parameters summing to one, aligned with method_names; the strongest method has the largest worth. NaN for a method that never appeared in a ranking. |
| quasi_se | np.ndarray | Quasi-standard-error per method (qvcalc), aligned with method_names. These allow a reference-free comparison of any two methods, unlike the model standard errors which are relative to a reference method. |
| log_worth | np.ndarray | Log-worth (ability) per method, aligned with method_names, on the scale the model is fit; the reference method is fixed at 0. |
| n_rankings | int | Number of dataset rankings the model was fit on (rankings with fewer than two ranked methods are dropped). |
| connected | bool | True when the win-loss network is strongly connected, the condition for finite worth estimates without pseudo-rankings. The fit uses the package default pseudo-rankings, so it returns estimates either way, but a False here flags that the estimates lean on that prior. |
| npseudo | float | The number of pseudo-rankings added against a hypothetical item. |
| loglik, df, aic | Model fit statistics. | |
| warnings | tuple[str, …] | Warnings raised by PlackettLuce during the fit. |
Methods
| Name | Description |
|---|---|
| ranking | Method names ordered by worth, strongest first. |
| top_tool | The method with the largest worth. |
ranking
heterogeneity.plackett_luce.PlackettLuceReport.ranking()
Method names ordered by worth, strongest first.
top_tool
heterogeneity.plackett_luce.PlackettLuceReport.top_tool()
The method with the largest worth.
Functions
| Name | Description |
|---|---|
| plackett_luce | Fit a Plackett-Luce model on per-dataset rankings of the methods. |
| plackett_luce_available | Return True when Rscript and the PlackettLuce and qvcalc packages are present. |
| rankings_from_matrix | Turn a method by dataset score matrix into a per-dataset ranking matrix. |
plackett_luce
heterogeneity.plackett_luce.plackett_luce(matrix, method_names, polarity='higher_is_better', npseudo=0.5)
Fit a Plackett-Luce model on per-dataset rankings of the methods.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
matrix |
np.ndarray | Array of shape (n_methods, n_datasets) for one metric. |
required |
method_names |
Sequence[str] | Length n_methods labels, the items being ranked. |
required |
polarity |
str | "higher_is_better" or "lower_is_better", used to orient each dataset’s ranking. |
'higher_is_better' |
npseudo |
float | Number of pseudo-rankings against a hypothetical item, the package device that keeps the worth estimates finite when the ranking network is weakly connected. The PlackettLuce default is 0.5; set 0 for the plain maximum-likelihood fit on a strongly connected design. | 0.5 |
Returns
| Type | Description |
|---|---|
| PlackettLuceReport |
Raises
| Type | Description |
|---|---|
| ValueError | For shape, length, or polarity problems, or if fewer than two rankings survive. |
| RNotAvailableError | If the R toolchain with PlackettLuce is not available. |
| RExecutionError | If the R subprocess fails. |
plackett_luce_available
heterogeneity.plackett_luce.plackett_luce_available()
Return True when Rscript and the PlackettLuce and qvcalc packages are present.
rankings_from_matrix
heterogeneity.plackett_luce.rankings_from_matrix(matrix, polarity)
Turn a method by dataset score matrix into a per-dataset ranking matrix.
Each dataset (a column) becomes one ranking of the methods: rank 1 is the best method on that dataset, ties share a rank (competition ranking), and a method with a missing score is left out of that dataset’s ranking, encoded as 0 in the PlackettLuce convention. “Best” is resolved through the metric polarity.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
matrix |
np.ndarray | Array of shape (n_methods, n_datasets) for one metric. |
required |
polarity |
str | "higher_is_better" or "lower_is_better". |
required |
Returns
| Type | Description |
|---|---|
| numpy.ndarray | Integer array of shape (n_datasets, n_methods) with rank 1 for the best method, ties shared, and 0 for a method absent from that ranking. |
Raises
| Type | Description |
|---|---|
| ValueError | If matrix is not 2D, has fewer than two methods, or polarity is not recognised. |