pairwise-comparison-framework 1.0.0__tar.gz

pairwise_comparison_framework-1.0.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.3
+Name: pairwise-comparison-framework
+Version: 1.0.0
+Summary: A framework for characterizing and predicting pairwise comparisons using user clustering and matrix completion
+Author: Henrique Chaves
+Author-email: Henrique Chaves <henriquechaves@poli.ufrj.br>
+License: MIT
+Requires-Dist: matplotlib>=3.10.7
+Requires-Dist: networkx>=3.5
+Requires-Dist: numpy>=2.3.3
+Requires-Dist: pandas>=2.3.3
+Requires-Dist: pydantic>=2.11.9
+Requires-Dist: scikit-learn>=1.7.2
+Requires-Dist: scipy>=1.16.2
+Requires-Dist: fancyimpute>=0.7.0
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# Pairwise Comparison Framework
+
+A Python framework for clustering users based on their pairwise comparison patterns and predicting missing comparisons via matrix completion.
+
+This project was developed as part of a final thesis (TCC) at the Escola Politécnica, Universidade Federal do Rio de Janeiro (UFRJ).
+
+## Overview
+
+The framework operates in two stages:
+
+1. **Clustering** (Stage 1): Each user's pairwise comparisons are modeled as a weighted directed graph. Shortest-path-length matrices serve as structural preference signatures, a custom distance metric measures user similarity, and MDS + K-Means produces the final clusters.
+
+2. **Prediction** (Stage 2): A sparse comparison matrix is built from all users' data. Matrix completion (Iterative SVD or KNN) fills in missing entries. Applying completion within each cluster improves prediction accuracy over a global model.
+
+## Installation
+
+Requires Python 3.13+. Install with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv sync
+```
+
+Or with pip:
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+### Clustering
+
+```python
+import pairwise_comparison_framework as pcf
+
+clusterizer = pcf.Clusterizer()
+clusterizer.load_data("data/sample/comparisons.json", "data/sample/labels.json")
+
+# Visualize a user's preference graph
+clusterizer.plot_graph("user_id", with_labels=True)
+
+# Get item rankings via PageRank
+clusterizer.get_ranking("user_id", with_labels=True)
+
+# Cluster users
+clusters = clusterizer.get_user_clusters(n_clusters=3)
+
+# Assess cluster quality
+clusterizer.get_silhouette_scores(n_clusters=3)
+clusterizer.get_elbow_data(max_clusters=10)
+clusterizer.plot_clusters(n_clusters=3)
+```
+
+### Prediction
+
+```python
+# Iterative SVD (default)
+predictor = pcf.Predictor(impute_method="svd", impute_rank=1)
+predictor.load_data("data/sample/comparisons.json", "data/sample/labels.json")
+
+# Or KNN imputation
+predictor = pcf.Predictor(impute_method="knn", impute_k=5)
+predictor.load_data("data/sample/comparisons.json", "data/sample/labels.json")
+
+# Predict missing comparisons
+completed_matrix = predictor.predict()
+
+# Controlled evaluation: global vs per-cluster
+results = predictor.evaluate_global_vs_clusters(
+    clusters, n_rounds=50, test_size=0.2
+)
+```
+
+## Data Format
+
+### Comparisons (`comparisons.json`)
+
+A JSON array of user comparison records. Each comparison score answers "How much more preferred is the first item over the second?":
+
+- `2`: first item much more preferred
+- `1`: first item more preferred
+- `0`: equally preferred (tie)
+- `-1`: second item more preferred
+- `-2`: second item much more preferred
+
+```json
+[
+  {
+    "user_id": "user_01",
+    "comparisons": [
+      {
+        "first_item_id": "item_01",
+        "second_item_id": "item_02",
+        "score": 2
+      }
+    ]
+  }
+]
+```
+
+### Labels (`labels.json`, optional)
+
+A JSON array mapping item IDs to human-readable names:
+
+```json
+[
+  {
+    "item_id": "item_01",
+    "label": "Oranges"
+  }
+]
+```
+
+## Notebooks
+
+| Notebook | Description |
+|----------|-------------|
+| `notebooks/clustering.ipynb` | Clustering pipeline demo with sample data |
+| `notebooks/prediction.ipynb` | Prediction pipeline demo with sample data |
+| `notebooks/epfl_analysis.ipynb` | Full analysis on the EPFL food preference dataset (private dataset, not included) |
+
+## Project Structure
+
+```
+pairwise-comparison-framework/
+├── src/pairwise_comparison_framework/
+│   ├── __init__.py          # Exports Clusterizer, Predictor
+│   ├── _base.py             # Shared data loading logic
+│   ├── models/              # Pydantic data models
+│   ├── clusterizer/         # Stage 1: clustering pipeline
+│   └── predictor/           # Stage 2: prediction pipeline
+├── data/
+│   └── sample/              # Small sample dataset (wine preferences)
+└── notebooks/               # Jupyter notebooks
+```
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

pairwise_comparison_framework-1.0.0/README.md

@@ -0,0 +1,139 @@
+# Pairwise Comparison Framework
+
+A Python framework for clustering users based on their pairwise comparison patterns and predicting missing comparisons via matrix completion.
+
+This project was developed as part of a final thesis (TCC) at the Escola Politécnica, Universidade Federal do Rio de Janeiro (UFRJ).
+
+## Overview
+
+The framework operates in two stages:
+
+1. **Clustering** (Stage 1): Each user's pairwise comparisons are modeled as a weighted directed graph. Shortest-path-length matrices serve as structural preference signatures, a custom distance metric measures user similarity, and MDS + K-Means produces the final clusters.
+
+2. **Prediction** (Stage 2): A sparse comparison matrix is built from all users' data. Matrix completion (Iterative SVD or KNN) fills in missing entries. Applying completion within each cluster improves prediction accuracy over a global model.
+
+## Installation
+
+Requires Python 3.13+. Install with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv sync
+```
+
+Or with pip:
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+### Clustering
+
+```python
+import pairwise_comparison_framework as pcf
+
+clusterizer = pcf.Clusterizer()
+clusterizer.load_data("data/sample/comparisons.json", "data/sample/labels.json")
+
+# Visualize a user's preference graph
+clusterizer.plot_graph("user_id", with_labels=True)
+
+# Get item rankings via PageRank
+clusterizer.get_ranking("user_id", with_labels=True)
+
+# Cluster users
+clusters = clusterizer.get_user_clusters(n_clusters=3)
+
+# Assess cluster quality
+clusterizer.get_silhouette_scores(n_clusters=3)
+clusterizer.get_elbow_data(max_clusters=10)
+clusterizer.plot_clusters(n_clusters=3)
+```
+
+### Prediction
+
+```python
+# Iterative SVD (default)
+predictor = pcf.Predictor(impute_method="svd", impute_rank=1)
+predictor.load_data("data/sample/comparisons.json", "data/sample/labels.json")
+
+# Or KNN imputation
+predictor = pcf.Predictor(impute_method="knn", impute_k=5)
+predictor.load_data("data/sample/comparisons.json", "data/sample/labels.json")
+
+# Predict missing comparisons
+completed_matrix = predictor.predict()
+
+# Controlled evaluation: global vs per-cluster
+results = predictor.evaluate_global_vs_clusters(
+    clusters, n_rounds=50, test_size=0.2
+)
+```
+
+## Data Format
+
+### Comparisons (`comparisons.json`)
+
+A JSON array of user comparison records. Each comparison score answers "How much more preferred is the first item over the second?":
+
+- `2`: first item much more preferred
+- `1`: first item more preferred
+- `0`: equally preferred (tie)
+- `-1`: second item more preferred
+- `-2`: second item much more preferred
+
+```json
+[
+  {
+    "user_id": "user_01",
+    "comparisons": [
+      {
+        "first_item_id": "item_01",
+        "second_item_id": "item_02",
+        "score": 2
+      }
+    ]
+  }
+]
+```
+
+### Labels (`labels.json`, optional)
+
+A JSON array mapping item IDs to human-readable names:
+
+```json
+[
+  {
+    "item_id": "item_01",
+    "label": "Oranges"
+  }
+]
+```
+
+## Notebooks
+
+| Notebook | Description |
+|----------|-------------|
+| `notebooks/clustering.ipynb` | Clustering pipeline demo with sample data |
+| `notebooks/prediction.ipynb` | Prediction pipeline demo with sample data |
+| `notebooks/epfl_analysis.ipynb` | Full analysis on the EPFL food preference dataset (private dataset, not included) |
+
+## Project Structure
+
+```
+pairwise-comparison-framework/
+├── src/pairwise_comparison_framework/
+│   ├── __init__.py          # Exports Clusterizer, Predictor
+│   ├── _base.py             # Shared data loading logic
+│   ├── models/              # Pydantic data models
+│   ├── clusterizer/         # Stage 1: clustering pipeline
+│   └── predictor/           # Stage 2: prediction pipeline
+├── data/
+│   └── sample/              # Small sample dataset (wine preferences)
+└── notebooks/               # Jupyter notebooks
+```
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

pairwise_comparison_framework-1.0.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "pairwise-comparison-framework"
+version = "1.0.0"
+description = "A framework for characterizing and predicting pairwise comparisons using user clustering and matrix completion"
+readme = "README.md"
+authors = [
+    { name = "Henrique Chaves", email = "henriquechaves@poli.ufrj.br" }
+]
+requires-python = ">=3.13"
+license = {text = "MIT"}
+dependencies = [
+    "matplotlib>=3.10.7",
+    "networkx>=3.5",
+    "numpy>=2.3.3",
+    "pandas>=2.3.3",
+    "pydantic>=2.11.9",
+    "scikit-learn>=1.7.2",
+    "scipy>=1.16.2",
+    "fancyimpute>=0.7.0",
+]
+[build-system]
+requires = ["uv_build>=0.8.4,<0.9.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "jupyter>=1.1.1",
+]

pairwise_comparison_framework-1.0.0/src/pairwise_comparison_framework/__init__.py

@@ -0,0 +1,4 @@
+from .clusterizer import Clusterizer
+from .predictor import Predictor
+
+__all__ = ["Clusterizer", "Predictor"]

pairwise_comparison_framework-1.0.0/src/pairwise_comparison_framework/_base.py

@@ -0,0 +1,59 @@
+import json
+
+from .models import ItemLabel, UserComparisons
+
+
+class BaseDataLoader:
+    """Shared data-loading logic for classes that consume comparison data.
+
+    Provides `_load_comparisons` and `_load_labels` together with the
+    `comparisons` and `labels` attributes they populate. Subclasses
+    should call `super().__init__()` and then perform their own
+    initialisation.
+    """
+
+    comparisons: list[UserComparisons]
+    labels: list[ItemLabel]
+
+    def __init__(self) -> None:
+        self.comparisons = []
+        self.labels = []
+
+    def _load_comparisons(self, filename: str) -> None:
+        """Load pairwise comparisons from a JSON file.
+
+        The file must contain a JSON array of objects, each with a
+        `user_id` and a `comparisons` list.
+
+        Args:
+            filename: Path to the JSON file.
+        """
+        with open(filename, "r") as f:
+            data = json.load(f)
+
+        if not isinstance(data, list):
+            raise ValueError("comparisons must be a list")
+
+        self.comparisons = [UserComparisons(**item) for item in data]
+
+        print(f"Loaded pairwise comparisons from {len(self.comparisons)} users")
+        print(
+            f"Total amount of pairwise comparisons: "
+            f"{sum(len(user.comparisons) for user in self.comparisons)}"
+        )
+
+    def _load_labels(self, filename: str) -> None:
+        """Load item labels from a JSON file.
+
+        Args:
+            filename: Path to the JSON file containing a list of
+                `{"item_id": ..., "label": ...}` objects.
+        """
+        with open(filename, "r") as f:
+            data = json.load(f)
+
+        if not isinstance(data, list):
+            raise ValueError("labels must be a list")
+
+        self.labels = [ItemLabel(**item) for item in data]
+        print(f"Loaded labels from {len(self.labels)} items")