API Reference

This section documents the main modules and classes in the Dueling Bandit Toolkit.

Modules

class dueling_bandit.environment.DuelingBanditEnv(P: ndarray, features: Optional[ndarray] = None, seed: Optional[int] = None)[source]

Bases: object

Dueling Bandit environment with Bradley-Terry model.

P: ndarray
best_arm() → int[source]

Return the index of the item with the highest BTL score.

delta12() → float[source]

Compute the separation metric Delta_1,2.

duel(a: int, b: int) → Tuple[int, int][source]

Perform a duel between two items.

features: Optional[ndarray] = None
classmethod random_bt(k: int, d: int = 0, seed: Optional[int] = None) → DuelingBanditEnv[source]

Generate a random Bradley-Terry environment.

seed: Optional[int] = None
true_rank() → ndarray[source]

Return the true ranking of items.

class dueling_bandit.environment.RankCentrality(k: int)[source]

Bases: object

Rank Centrality for spectral ranking from pairwise comparisons.

stationary_distribution(wins: ndarray, losses: ndarray) → ndarray[source]

Compute stationary distribution using Rank Centrality.

Parameters

  • wins (np.ndarray) – Win counts (k x k).

  • losses (np.ndarray) – Loss counts (k x k).

Returns

Stationary distribution (pi).

Return type

np.ndarray

dueling_bandit.datasets.load_jester_data(k: int = 20, data_path: str = 'data/jester_ratings.csv', seed: Optional[int] = None) → ndarray[source]

Load Jester dataset and return a ratings matrix for k jokes.

Parameters

  • k (int) – Number of jokes to select.

  • data_path (str) – Path to Jester ratings CSV file.

  • seed (Optional[int]) – Random seed for reproducibility.

Returns

Ratings matrix (k x users) with NaN for missing values.

Return type

np.ndarray

dueling_bandit.datasets.load_movielens_data(k: int = 20, data_path: str = 'data/ml-100k/u.data', seed: Optional[int] = None) → ndarray[source]

Load MovieLens dataset and return a ratings matrix for k movies.

Parameters

  • k (int) – Number of movies to select.

  • data_path (str) – Path to MovieLens ratings file.

  • seed (Optional[int]) – Random seed for reproducibility.

Returns

Ratings matrix (k x users) with NaN for missing values.

Return type

np.ndarray

dueling_bandit.datasets.ratings_to_preference_matrix(ratings: ndarray) → ndarray[source]

Convert ratings matrix to pairwise preference matrix using logistic function.

Parameters

ratings (np.ndarray) – Ratings matrix (items x users).

Returns

Preference matrix (items x items).

Return type

np.ndarray

dueling_bandit.plotting.plot_all_metrics(results: Dict[str, Dict[int, Dict[str, Dict[str, ndarray]]]], datasets: List[str], budgets: List[int], metrics: Optional[List[str]] = None, save_dir: Optional[str] = None)[source]

Plot all metrics for all datasets and budgets.

Parameters

  • results – Dictionary of results per dataset, budget, and agent.

  • datasets – List of dataset names.

  • budgets – List of budgets.

  • metrics – List of metrics to plot (default: all).

  • save_dir – Directory to save plots.

dueling_bandit.plotting.plot_metric(results: Dict[int, Dict[str, Dict[str, ndarray]]], budget: int, dataset: str, metric: str, show_error_bars: bool = True, save_path: Optional[str] = None)[source]

Plot a single metric for all agents.

Parameters

  • results – Dictionary of results per budget and agent.

  • budget – Budget to plot.

  • dataset – Dataset name.

  • metric – Metric to plot (e.g., ‘mean_regret’).

  • show_error_bars – Whether to show standard deviation error bars.

  • save_path – Path to save the figure.