Metadata-Version: 2.4
Name: pyrevealed
Version: 0.4.2
Summary: Behavioral Signal Analysis for User Understanding - Detect bots, shared accounts, and UI confusion
Project-URL: Homepage, https://github.com/rawatpranjal/PyRevealed
Project-URL: Documentation, https://pyrevealed.readthedocs.io
Project-URL: Repository, https://github.com/rawatpranjal/PyRevealed
Author: PyRevealed Contributors
License: MIT
License-File: LICENSE
Keywords: anomaly-detection,behavioral-analysis,bot-detection,consistency-check,fraud-detection,machine-learning,revealed-preference,user-analytics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: networkx>=3.0
Requires-Dist: numba>=0.58.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: scipy>=1.10.0
Provides-Extra: all
Requires-Dist: jupyter>=1.0.0; extra == 'all'
Requires-Dist: matplotlib>=3.7.0; extra == 'all'
Requires-Dist: mypy>=1.0; extra == 'all'
Requires-Dist: pandas>=2.0.0; extra == 'all'
Requires-Dist: pydata-sphinx-theme>=0.14; extra == 'all'
Requires-Dist: pytest-cov>=4.0; extra == 'all'
Requires-Dist: pytest>=7.0; extra == 'all'
Requires-Dist: ruff>=0.1.0; extra == 'all'
Requires-Dist: seaborn>=0.12.0; extra == 'all'
Requires-Dist: sphinx-autodoc-typehints>=1.25; extra == 'all'
Requires-Dist: sphinx-copybutton>=0.5; extra == 'all'
Requires-Dist: sphinx>=7.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: pydata-sphinx-theme>=0.14; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints>=1.25; extra == 'docs'
Requires-Dist: sphinx-copybutton>=0.5; extra == 'docs'
Requires-Dist: sphinx>=7.0; extra == 'docs'
Provides-Extra: notebooks
Requires-Dist: jupyter>=1.0.0; extra == 'notebooks'
Requires-Dist: matplotlib>=3.7.0; extra == 'notebooks'
Requires-Dist: pandas>=2.0.0; extra == 'notebooks'
Requires-Dist: seaborn>=0.12.0; extra == 'notebooks'
Provides-Extra: viz
Requires-Dist: matplotlib>=3.7.0; extra == 'viz'
Description-Content-Type: text/markdown

# PyRevealed

**Production-ready revealed preference analysis.** Test if choices are internally consistent, quantify behavioral consistency, and analyze decision patterns.

> Based on: Chambers, C. P., & Echenique, F. (2016). *Revealed Preference Theory*. Cambridge University Press.

[![PyPI](https://img.shields.io/pypi/v/pyrevealed)](https://pypi.org/project/pyrevealed/)
[![Documentation](https://readthedocs.org/projects/pyrevealed/badge/?version=latest)](https://pyrevealed.readthedocs.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

## Installation

```bash
pip install pyrevealed
```

For visualization support:
```bash
pip install pyrevealed[viz]
```

## Quick Start

```python
from pyrevealed import BehaviorLog, validate_consistency, compute_integrity_score
import numpy as np

# Two purchase observations: prices and quantities
log = BehaviorLog(
    cost_vectors=np.array([[1.0, 2.0], [2.0, 1.0]]),
    action_vectors=np.array([[3.0, 1.0], [1.0, 3.0]])
)

# Check if choices are consistent with utility maximization
is_consistent = validate_consistency(log)  # True

# Get integrity score (0 = inconsistent, 1 = perfectly consistent)
result = compute_integrity_score(log)
print(f"Integrity: {result.efficiency_index:.2f}")  # 1.00
```

## Core Functions

| Function | Returns | Score Meaning |
|----------|---------|---------------|
| `validate_consistency(log)` | `bool` | True = rational |
| `compute_integrity_score(log)` | `AEIResult` (0-1) | 1 = perfect |
| `compute_confusion_metric(log)` | `MPIResult` (0-1) | 0 = no cycles |
| `fit_latent_values(log)` | `UtilityRecoveryResult` | Utility values |
| `compute_minimal_outlier_fraction(log)` | `HoutmanMaksResult` (0-1) | 0 = all consistent |

**Quick interpretation**: Integrity >= 0.95 is excellent, >= 0.90 is good, < 0.70 indicates problems.

## Menu-Based Choice

For discrete choices without prices (surveys, recommendations, voting):

```python
from pyrevealed import MenuChoiceLog, validate_menu_sarp, fit_menu_preferences

log = MenuChoiceLog(
    menus=[frozenset({0, 1, 2}), frozenset({1, 2}), frozenset({0, 2})],
    choices=[0, 1, 0],
    item_labels=["Pizza", "Burger", "Salad"]
)

result = validate_menu_sarp(log)
print(f"Consistent: {result.is_consistent}")

prefs = fit_menu_preferences(log)
print(f"Preference order: {prefs.preference_order}")
```

## Documentation

**[Full Documentation](https://pyrevealed.readthedocs.io/)**

### Tutorials

1. **[Budget-Based Analysis](https://pyrevealed.readthedocs.io/en/latest/tutorial.html)** - GARP, CCEI, MPI, Bronars power
2. **[Menu-Based Choice](https://pyrevealed.readthedocs.io/en/latest/tutorial_menu_choice.html)** - WARP, SARP, attention models
3. **[Welfare Analysis](https://pyrevealed.readthedocs.io/en/latest/tutorial_welfare.html)** - CV, EV, deadweight loss
4. **[Demand Analysis](https://pyrevealed.readthedocs.io/en/latest/tutorial_demand_analysis.html)** - Slutsky matrix, integrability
5. **[Stochastic & Production](https://pyrevealed.readthedocs.io/en/latest/tutorial_advanced.html)** - Logit, IIA, firm behavior
6. **[E-Commerce at Scale](https://pyrevealed.readthedocs.io/en/latest/tutorial_ecommerce.html)** - 1.85M Amazon transactions

## Features

- **Consistency Testing**: GARP, WARP, SARP axiom verification
- **Behavioral Metrics**: Afriat Efficiency Index, Money Pump Index
- **Utility Recovery**: Reconstruct utility functions from choices
- **ML Integration**: sklearn-compatible `PreferenceEncoder`
- **Multiple Data Types**: Budgets, menus, stochastic choice, production
- **Production Ready**: Fast parallel processing, validated against R's revealedPrefs

## License

MIT
