prefgraph 0.5.13

Revealed preference analysis at scale — rationality scores, efficiency indices, and utility recovery. Rust engine, Python interface.

PrefGraph

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

pip install "prefgraph[datasets]"

Quick Example

Score how consistently each user's choices align with rational utility maximization. Paste and run:

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

users = load_demo()  # 100 synthetic consumers, no download needed
engine = Engine(metrics=["garp", "ccei", "mpi", "harp", "hm"])
results = engine.analyze_arrays(users)

for r in results[:5]:
    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. Use them for fraud detection, user segmentation, A/B testing, churn prediction, or personalization.

Your Data

Have a pandas DataFrame? One line:

import prefgraph as rp

# Transaction logs (one row per item per time)
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, items 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
results = rp.analyze(df, user_col="user_id",
                     menu_col="shown_items", choice_col="clicked")

Returns a pandas DataFrame with one row per user. Customize with metrics=["garp", "ccei", "mpi", "hm"]. Handle missing data with nan_policy="drop".

Scores

Score	Field	What it measures	Range
Consistency	is_garp	Are choices rationalizable? (GARP)	bool
Efficiency	ccei	How close to perfectly rational? (Afriat)	0-1
Exploitability	mpi	Value left on the table per choice (Karp cycle)	0-1
Homotheticity	is_harp	Do preferences scale with budget?	bool
Noise fraction	hm_consistent/hm_total	Fraction of rationalizable choices (Houtman-Maks)	0-1
Utility recovery	utility_success	Can latent utility be reconstructed? (Afriat LP)	bool
Per-obs efficiency	vei_mean	Average efficiency across observations (Varian)	0-1

Which API?

	Engine	Function API
Use case	Score thousands of users	Deep-dive one user
Speed	10,000+ users/sec (Rust)	Single-user
Returns	EngineResult (flat scores)	GARPResult, AEIResult, etc. (matrices, cycles, graphs)
Metrics	7 (garp, ccei, mpi, harp, hm, utility, vei) + network	30+ algorithms
Input	list[(prices, quantities)]	BehaviorLog

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
session = BehaviorLog(cost_vectors=prices, action_vectors=quantities)
garp = validate_consistency(session)       # GARPResult with violation cycles, matrices
ccei = compute_integrity_score(session)    # AEIResult with binary search details

4 Choice Categories

                Test (bool)     Score (0-1)     Recover (vector)  Structure (bool)
Budget          GARP, WARP      CCEI, MPI, HM   Utility, CV/EV    HARP, Separability
Discrete        SARP, RUM LP    HM (menu)        Ordinal utility   Congruence
Production      Prod GARP       Prod CCEI        Tech efficiency   Cost minimization
Intertemporal   Exp discount    —                Discount delta    Quasi-hyperbolic

Category	Input format	Example domain
Budget	(prices T×K, quantities T×K)	E-commerce, grocery, food delivery
Discrete	(menus, choices) or (menus, frequencies)	Surveys, A/B tests, recommendations
Production	(input_p, input_q, output_p, output_q)	Supply chain, manufacturing
Intertemporal	(amounts, dates, chosen)	Subscriptions, savings, loyalty

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.

Users	Metrics	Time	Throughput
1,000	5	0.1s	10,000/s
10,000	5	2s	5,000/s
100,000	5	20s	5,000/s

18-100x faster than pure Python. Memory stays bounded via streaming chunks.

Documentation

Full docs — examples, theory, API reference, application case studies.

E-commerce benchmarks — 6 datasets, 117K users, 12 targets. RP features add 0–2% lift over RFM baselines; on Taobao, RP-only (0.925) beats the engagement baseline (0.913).

15 dataset loaders — Dunnhumby, Instacart, H&M, Taobao, and 11 more real-world datasets.

License

MIT