Ranker

A robust and flexible TypeScript library for ranking items based on pairwise comparisons using an advanced Elo-like rating system.

Table of Contents

• Ranker
  • Table of Contents
  • Features
  • Installation
  • Quick Start
  • Configuration
    • RankerConfig
    • Effects of Parameters
    • Progress Tracking
      • ProgressParams
  • API Reference
    • Ranker Class
      • Constructor
      • Methods
    • Types
  • Advanced Usage
    • Batch Processing
    • Rating Delta Analysis
  • Mathematical Foundation
  • Contributing

Features

• 🚀 Easy-to-use API for managing rankable items and their comparisons
• ⚙️ Highly configurable ranking parameters
• 🧠 Intelligent calculation of optimal next comparison
• 📊 Comprehensive progress tracking for ranking stability
• 📈 Detailed item statistics and historical data
• 🔧 Full TypeScript support with type definitions
• 🧮 Transparent mathematical model with customizable parameters

Installation

Install Ranker using npm:

npm install ranker

Or using yarn:

yarn add ranker

Quick Start

Get up and running with Ranker in just a few lines of code:

import { Ranker, RankableItem, ComparisonResult } from "eloranker";

// Initialize items
const initialItems: RankableItem[] = [
  { id: "item1", initialRating: 1500 },
  { id: "item2", initialRating: 1500 },
  { id: "item3", initialRating: 1500 },
];

// Create a new Ranker instance
const ranker = new Ranker(initialItems, { kFactor: 32 });

// Add a comparison result
const result: ComparisonResult = {
  itemId1: "item1",
  itemId2: "item2",
  result: "win",
  timestamp: Date.now(),
};

const ratingDelta = ranker.addComparisonResult(result);
console.log(`Rating change: ${ratingDelta}`);

// Get current rankings
const rankings = ranker.getRankings();
console.log("Current rankings:", rankings);

Configuration

Customize Ranker's behavior with the following configuration options:

RankerConfig

Parameter	Type	Default	Description
kFactor	number	32	Determines the maximum rating change per comparison
minimumComparisons	number	20	Minimum comparisons before considering an item's ranking stable
defaultInitialRating	number	1500	Starting rating for new items
minRating	number	0	Minimum possible rating for any item

Example configuration:

const ranker = new Ranker(initialItems, {
  kFactor: 24,
  minimumComparisons: 30,
  defaultInitialRating: 1600,
  minRating: 100,
});

Effects of Parameters

• kFactor: Higher values make the system more responsive but potentially volatile. Lower values provide more stability but slower adaptation.
• minimumComparisons: Increasing this value requires more data for stability, potentially increasing accuracy but increasing number of comparisons.
• defaultInitialRating: Adjust based on prior knowledge about the general strength of new items.
• minRating: Prevents extremely low ratings, which may be desirable in some applications.

Progress Tracking

Monitor ranking stability with the getProgress method:

const progress = ranker.getProgress({
  ratingChangeThreshold: 5,
  stableComparisonsThreshold: 10,
});
console.log(`Ranking progress: ${progress * 100}%`);

ProgressParams

Parameter	Type	Description
ratingChangeThreshold	number	Maximum allowed rating change for stability
stableComparisonsThreshold	number	Number of recent comparisons to check

• Lower ratingChangeThreshold increases accuracy but slows stabilization.
• Higher stableComparisonsThreshold increases confidence but takes longer to achieve.

API Reference

Ranker Class

Constructor

constructor(initialItems: RankableItem[], config: Partial<RankerConfig>)

Methods

Method	Description	Return Type
addItem(id: string, initialRating?: number)	Add a new item to the ranking system	void
removeItem(id: string)	Remove an item from the ranking system	void
addComparisonResult(result: ComparisonResult)	Add a new comparison result	number (rating delta)
getNextComparison()	Get the optimal next comparison	[string, string] | null
getItemStats(id: string)	Get statistics for a specific item	RankableItem
getRankings()	Get current rankings of all items	RankableItem[]
getItemCount()	Get the total number of items	number
getAllItems()	Get all items in the system	RankableItem[]
getProgress(params: ProgressParams)	Get the current progress/stability of rankings	number
getItemHistory(id: string)	Get rating history for an item	Array<{ rating: number; timestamp: number }>

Types

type RankableItem = {
  id: string;
  initialRating: number;
  currentRating: number;
  comparisons: number;
  wins: number;
  losses: number;
  ties: number;
  lastComparisonTime: number | null;
  ratingHistory: Array<{ rating: number; timestamp: number }>;
};

type ComparisonResult = {
  itemId1: string;
  itemId2: string;
  result: "win" | "loss" | "tie";
  timestamp: number;
  metadata?: any;
};

type RankerConfig = {
  kFactor: number;
  minimumComparisons: number;
  defaultInitialRating: number;
  minRating: number;
};

type ProgressParams = {
  ratingChangeThreshold: number;
  stableComparisonsThreshold: number;
};

Advanced Usage

Batch Processing

For systems with many items, implement batched processing:

const allItems = ranker.getAllItems();
const batchSize = 100;

for (let i = 0; i < allItems.length; i += batchSize) {
  const batch = allItems.slice(i, i + batchSize);
  // Process batch...
}

Rating Delta Analysis

Use the rating delta to trigger events or updates:

const SIGNIFICANT_CHANGE_THRESHOLD = 50;

const ratingDelta = ranker.addComparisonResult(result);
if (ratingDelta > SIGNIFICANT_CHANGE_THRESHOLD) {
  console.log("Significant ranking change detected!");
  // Trigger updates, notifications, etc.
}

Mathematical Foundation

Ranker uses an advanced Elo-like rating system. Here are the key equations:

1. Expected Score Calculation:

   The expected score for player A when competing against player B is:

   $E(A) = \frac{1}{1 + 10^{(R_B - R_A) / 400}}$

   Where $R_A$ and $R_B$ are the current ratings of players A and B.

2. Rating Update:

   After a comparison, ratings are updated using:

   $R_{new} = R_{old} + K \cdot (S - E)$

   Where:

   • $R_{new}$ is the new rating
   • $R_{old}$ is the old rating
   • $K$ is the k-factor (configurable)
   • $S$ is the actual score (1 for win, 0.5 for tie, 0 for loss)
   • $E$ is the expected score from step 1

3. Rating Delta:

   The rating delta returned by addComparisonResult is:

   $\Delta = |R_{new_A} - R_{old_A}| + |R_{new_B} - R_{old_B}|$

   This represents the total change in ratings for both items.

These equations ensure:

• Winning against a higher-rated opponent yields a larger rating increase.
• Losing against a lower-rated opponent results in a larger rating decrease.
• The k-factor controls the maximum possible change from a single comparison.

Contributing

We welcome contributions to Ranker! Here's how you can help:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request