How rawatpranjal/econirl works
1. What this repo is
- econirl is a Python package for structural dynamic discrete choice and inverse reinforcement learning.
- The public API is sklearn-like: users load panel/trajectory data, fit an estimator, then run counterfactuals, inference, and visualization.
2. Top-level architecture
- The codebase is split into a reusable library in src/econirl/, a validation harness in validation/, public examples in examples/, and docs/tests around that core.
- The package is not a single-model project: it contains multiple estimator families sharing common primitives.
3. Data and domain inputs
- src/econirl/datasets/ provides loaders and packaged sample data for canonical case studies such as Rust bus, taxi/gridworld, citi bike, sepsis, supermarket, and others.
- src/econirl/environments/ defines the corresponding MDP/environment abstractions used by synthetic experiments and demonstrations.
- Many examples and tests rely on these bundled datasets rather than external live services.
4. Core modeling layer
- src/econirl/core/ contains the shared mathematical machinery: Bellman operators, occupancy measures, optimizer utilities, sufficient statistics, reward specs, and type definitions.
- This layer is the common dependency for both classical DDC estimators and IRL-style estimators, so it forms the main computational boundary of the package.
5. Estimator families
- src/econirl/estimators/ is the primary sklearn-style surface exposed to users; this is where NFXP, CCP, MPEC, NNES, TDCCP, MCEIRL, and neural variants live.
- src/econirl/estimation/ contains lower-level implementations and estimator orchestration logic, including adversarial methods like AIRL and AIRL-Het.
- src/econirl/contrib/ holds older or supplementary algorithms such as behavioral cloning, GAIL, max-margin IRL, max-ent IRL, Bayesian IRL, and Deep MaxEnt IRL.
6. Model representation and preferences
- src/econirl/forms/ handles how state/action/tabular/factored structures are represented and loaded.
- src/econirl/preferences/ defines reward/utility parameterizations, including linear, reward-based, action-utility, and neural cost forms.
- These modules are the bridge between raw data and estimator-specific optimization targets.
7. Training, optimization, and transition estimation
- src/econirl/transitions.py and src/econirl/estimation/transitions.py support estimating or working with transition dynamics.
- src/econirl/core/optimizer.py, src/econirl/core/solvers.py, and neural-specific estimators provide the optimization backend for likelihood, fixed-point, and adversarial objectives.
- src/econirl/rl/ppo.py is the one explicit RL training component, used mainly for imitation-learning style workflows.
8. Inference and uncertainty
- src/econirl/inference/ provides post-estimation analysis: standard errors, bootstrap, profile likelihood, fit metrics, hypothesis tests, identifiability, sensitivity, and result containers.
- This layer is used after estimation, not during the core fit loop, and is important for the “structural” part of the package: recovering parameters and assessing uncertainty.
9. Counterfactuals, simulation, and evaluation
- src/econirl/simulation/ generates counterfactual and synthetic outcomes from fitted models.
- src/econirl/evaluation/ and src/econirl/visualization/ turn fitted models into benchmark metrics, convergence summaries, policy/value plots, and diagnostic views.
- A typical flow is: data in → estimator fit → counterfactual or policy simulation out → evaluation/visualization.
10. Replication and case studies
- src/econirl/replication/rust1987/ packages a Rust bus replication workflow with exports, Monte Carlo routines, and tables.
- examples/ contains reproducible case studies and showcases; many are one-off scripts for a specific estimator/data combination.
- These examples act as architecture “integration points” showing how the library is intended to be composed in practice.
11. Validation subsystem
- validation/ is a separate, reproducible benchmark/validation harness with runners, metrics, and archived results JSON.
- It provides the strongest evidence boundary in the repo: each estimator has scoped validation tasks and stored outputs, which are also referenced in the README’s public evidence table.
- This means the repo distinguishes between the general-purpose library and the formal validation suite used to support claims about each method.
12. Tests and quality gates
- tests/ covers unit, integration, benchmark, and estimator-specific behavior across datasets, wrappers, convergence, identifiability, and API compatibility.
- .github/workflows/ci.yml, pyproject.toml, and the Makefile define packaging and CI automation; docs/ is built separately for Read the Docs.
- The presence of both validation artifacts and tests indicates two distinct quality layers: correctness/regression testing and empirical method validation.
13. Technology and runtime boundaries
- The package is pure Python at the repo level, with JAX configuration visible in src/econirl/_jax_config.py, suggesting JAX-backed numerical paths in some estimators.
- The public interface is library-first rather than service-first: there is no web server or database boundary in the architecture.
- External dependencies are mostly scientific-computing and plotting toolchains, with packaged data files and notebooks used for reproducibility rather than runtime integration.
Main entry points: estimators Estimators · core Core math · __init__.py econirl API · examples Showcases
Components 20
Library
Reusable Python package under src/econirl
- econirl API · Public package surface and import entry point
src/econirl/__init__.py - Core math · Bellman operators, occupancy measures, solvers, rewards, and types
src/econirl/core - Forms · Tabular, factored, and grid representations plus loaders
src/econirl/forms - Preferences · Linear, action-utility, reward, and neural cost forms
src/econirl/preferences - Datasets · Dataset loaders and bundled benchmark datasets
src/econirl/datasets - Environments · Synthetic and demo environment abstractions
src/econirl/environments - Estimators · Primary user-facing estimator family surface
src/econirl/estimators - Estimation logic · Lower-level implementations and estimator workflows
src/econirl/estimation - Contrib IRL · Supplementary and older imitation/IRL methods
src/econirl/contrib - Transitions · Transition-model utilities and estimation support
src/econirl/transitions.py - Inference · Standard errors, bootstrap, profile likelihood, tests, and sensitivity
src/econirl/inference - Simulation · Synthetic and counterfactual outcome generation
src/econirl/simulation - Evaluation · Benchmarking, convergence, and evaluation adapters
src/econirl/evaluation - Visualization · Policy and value visualization helpers
src/econirl/visualization - RL training · Explicit reinforcement-learning training component
src/econirl/rl/ppo.py - Rust replication · Rust 1987 export, Monte Carlo, and tables workflow
src/econirl/replication/rust1987
Validation
Benchmark harness and archived evidence
- Validation harness · Validation runner, metrics, and figures for estimator claims
validation/benchmark/harness.py - Validation results · Stored JSON outputs for estimator and simulation benchmarks
validation/results
Examples
Reproducible case studies and showcase scripts
- Showcases · Estimator and case-study scripts demonstrating intended usage
examples
Connections 24
- econirl API → Core math: uses · Public API is built on the shared mathematical layer
- econirl API → Forms: exposes · Package surface exposes representation helpers
- econirl API → Preferences: exposes · Package surface exposes preference models
- econirl API → Estimators: exports · Top-level package exports sklearn-style estimators
- Forms → Datasets: loads · Form loaders consume bundled datasets and samples
- Environments → Core math: relies on · Environments use core MDP and Bellman primitives
- Estimators → Core math: optimizes · Estimators depend on Bellman, occupancy, and solver utilities
- Estimators → Transitions: fits dynamics · Some estimators estimate or adapt transition models
- Estimators → Inference: analyzes · Estimator outputs feed post-estimation inference
- Estimators → Simulation: simulates · Fitted estimators produce counterfactual simulations
- Estimators → Evaluation: evaluates · Estimator runs are benchmarked and summarized
- Estimators → Visualization: visualizes · Estimator outputs can be plotted as policies and values
- Estimation logic → Estimators: implements · Lower-level orchestration backs the public estimator surface
- Contrib IRL → Core math: extends · Older IRL methods reuse shared optimization and reward machinery
- RL training → Core math: uses · PPO-based training uses shared types and objectives
- Rust replication → Simulation: runs · Replication workflow uses simulation and counterfactual generation
- Validation harness → Estimators: benchmarks · Validation harness exercises estimators under controlled tasks
- Validation harness → Validation results: writes · Harness stores archived benchmark outputs
- Showcases → Datasets: loads · Examples commonly start from bundled datasets
- Showcases → Estimators: demonstrates · Examples show fitting and comparison of estimators
- Showcases → Simulation: demonstrates · Examples often generate counterfactuals and diagnostics
- Docs site → Estimators: documents · Docs explain estimator usage and internals
- Docs site → Validation harness: reports · Docs reference validation and evidence tables
- Docs site → Showcases: showcases · Docs link to example workflows and studies