PrefGraph

Rationality scores for every user. Rust engine, Python interface.

pip install prefgraph

Quick Example

Score how consistently each user's choices align with rational utility maximization:

from prefgraph.datasets import load_demo
from prefgraph.engine import Engine

# 100 synthetic shoppers (prices x quantities), no download needed
users = load_demo()

# Engine scores every user in parallel via Rust/Rayon
engine = Engine(metrics=["garp", "ccei", "mpi", "harp", "hm"])
results = engine.analyze_arrays(users)

for r in results[:3]:
    print(r)

EngineResult: [+] GARP-consistent  ccei=1.0000  hm=15/15  (42us)
EngineResult: [-] 3 violations  ccei=0.8472  mpi=0.0231  hm=12/15  (38us)
EngineResult: [+] GARP-consistent  ccei=1.0000  hm=15/15  (35us)

Every score is a feature you can plug into downstream models. In our benchmarks across 11 e-commerce datasets, revealed preference features rank among the top ten by model importance but add near-zero marginal lift over well-constructed baselines. See the case studies for details.

Your Data

Have a DataFrame? One line:

import prefgraph as rp

# Transaction logs (one row per user x time x item)
results = rp.analyze(df, user_col="user_id", item_col="product",
                     cost_col="price", action_col="quantity", time_col="week")

# Wide format (one row per observation, goods as columns)
results = rp.analyze(df, user_col="user_id",
                     cost_cols=["price_A", "price_B"],
                     action_cols=["qty_A", "qty_B"])

# Menu/click data (which items were shown, which was picked)
results = rp.analyze(df, user_col="user_id",
                     menu_col="shown_items", choice_col="clicked")

Returns a DataFrame with one row per user. Customize with metrics=["garp", "ccei", "mpi", "hm"].

Scores

Which API?

Engine for batch scoring. Function API when you need violation details, observation/item graphs, or advanced tests:

from prefgraph import BehaviorLog, validate_consistency, compute_integrity_score

# 3 shopping trips, 2 goods
session = BehaviorLog(cost_vectors=prices, action_vectors=quantities)

# GARP: does a consistent utility function exist?
garp = validate_consistency(session)       # GARPResult with violation cycles, matrices

# CCEI: how much must budgets shrink to remove contradictions?
ccei = compute_integrity_score(session)    # AEIResult with binary search details

Budget and Menu Choices

PrefGraph supports two primary choice domains:

Performance

The Rust engine (rpt-core) handles graph algorithms and LP solving via Rayon thread pool. Python handles I/O and the user-facing API.

Memory stays flat via streaming chunks.

Documentation

Full docs at prefgraph.readthedocs.io:

• Loading Data - Parquet, DataFrame, synthetic generators
• Case Studies - LLM consistency, e-commerce benchmarks
• Algorithms - Implementation details
• API Reference - Full method reference

License

MIT