/structural-modeling

name: structural-modeling
argument-hint: "<model type or estimation problem>"
description: >-
  This skill covers structural econometric models. Use when the user is building, estimating, or debugging structural models — including BLP demand estimation, dynamic discrete choice, auction models, or any workflow involving moment conditions, nested fixed-point algorithms, or MPEC formulations. Triggers on "structural model", "moment conditions", "NFXP", "MPEC", "BLP", "random coefficients", "dynamic discrete choice", "CCP", "Rust model", "auction estimation", "GMM objective", "inner loop", "contraction mapping", or convergence/starting value problems in optimization-based estimation.

Structural Modeling

Reference for implementing structural econometric models: from economic model to moment conditions to estimated parameters. Covers the full workflow of taking a theoretical model, deriving its empirical content, and recovering structural parameters from data.

When to Use This Skill

Use when the user is:

• Specifying a structural model and deriving moment conditions
• Implementing NFXP or MPEC estimation routines
• Working with BLP-style demand systems (random coefficients logit)
• Building dynamic discrete choice models (Rust, Hotz-Miller CCP)
• Estimating auction models (first-price, ascending, common value)
• Debugging convergence failures in structural estimation
• Choosing between estimation approaches for a given model

Skip when:

• The task is reduced-form causal inference (use `causal-inference` skill)
• The task is pure simulation design (use `numerical-auditor` agent)
• The user just needs standard regression (statsmodels/linearmodels suffice)

Quick Reference: Structural Methods

| Method | Use Case | Key Package | Estimator | |--------|----------|-------------|-----------| | NFXP | Dynamic discrete choice (small state space) | `scipy.optimize` | MLE / GMM | | MPEC | Dynamic discrete choice (large state space, slow inner loop) | `cyipopt` (IPOPT) | MLE / GMM | | BLP | Differentiated products demand with RC logit | `pyblp` | GMM (2-step) | | CCP (Hotz-Miller) | Dynamic models, counterfactuals not needed | `scipy` | 2-step semiparametric | | GPV | First-price auctions, nonparametric values | `scipy` | Nonparametric | | Ascending auction | English auctions, private values | `scipy` | MLE on order statistics |

The Structural Estimation Workflow

Every structural estimation follows the same logical arc:

Economic Model → Equilibrium/Decision Rule → Observable Implications
    → Moment Conditions → Estimator → Optimization → Inference

Step 1: Model Specification

Define primitives clearly before writing any code:

# model_spec.py — Document structural primitives
"""
Model: Single-agent optimal stopping (Rust 1987 bus engine replacement)

State:    x_t ∈ {0, 1, ..., X_max}  (mileage bin)
Action:   a_t ∈ {0, 1}  (0 = maintain, 1 = replace)
Flow payoff:
    u(x, 0; θ) = -θ_1 * x - θ_2 * x²     (maintenance cost)
    u(x, 1; θ) = -RC                        (replacement cost)
Discount:  β = 0.9999 (fixed)
Shocks:    ε ~ Type 1 Extreme Value (logit errors)
"""

Document these before writing estimation code: agents, information, timing, payoff functional form, equilibrium concept.

Step 2: Derive Moment Conditions

| Source | Example | Estimator | |--------|---------|-----------| | Optimality conditions (FOCs) | Euler equations, Bellman optimality | GMM | | Equilibrium restrictions | Market clearing, Nash conditions | GMM / ML | | Distributional assumptions | Choice probabilities under logit errors | MLE | | Exclusion restrictions | Cost shifters excluded from demand | IV-GMM |

**Key question:** Just-identified → method of moments; over-identified → GMM with optimal weighting matrix; under-identified → revisit assumptions.

NFXP vs MPEC

Two dominant paradigms for models with latent quantities (unobserved heterogeneity, future expectations, equilibrium objects):

**NFXP (Nested Fixed-Point):** Solve the model in an inner loop for each parameter guess, evaluate likelihood/moments in an outer loop. Conceptually simple; inner loop must fully converge at every iteration — requires tight tolerance (1e-12, not 1e-6; see Su & Judd 2012).

**MPEC (Mathematical Programming with Equilibrium Constraints):** Reformulate as a single constrained optimization. No inner loop — solver handles everything; can be faster for large state spaces; requires IPOPT or KNITRO.

| Factor | Favors NFXP | Favors MPEC | |--------|-------------|-------------| | State space | Small (< 500 states) | Large (> 1000 states) | | Inner loop | Fast convergence (rate < 0.9) | Slow or fragile | | Solver availability | `scipy.optimize` sufficient | IPOPT/KNITRO available | | Debugging | Easier — isolate inner vs outer | Harder to diagnose constraint violations |

For full NFXP and MPEC code (Rust 1987 bus engine model), see `references/estimation-methods.md`.

BLP Demand Estimation

BLP (Berry, Levinsohn, Pakes 1995) is the workhorse for differentiated products demand. Use PyBLP whenever possible — it handles the difficult numerical details correctly.

import pyblp

# Define the problem
problem = pyblp.Problem(
    product_formulations=(
        pyblp.Formulation('1 + prices + x1 + x2'),       # linear (β)
        pyblp.Formulation('1 + prices + x1'),              # random coefficients (Σ)
    ),
    product_data=product_data,
    agent_data=agent_data
)

# Solve — always use multiple starting values; BLP objective is non-convex
results = problem.solve(
    sigma=sigma_init,
    optimization=pyblp.Optimization('l-bfgs-b', {'gtol': 1e-8}),
    iteration=pyblp.Iteration('squarem', {'atol': 1e-14}),
    method='2s'
)

For the full multi-start loop, two-step GMM, elasticity checks, instrument selection, and marginal cost computation, see `references/estimation-methods.md`.

**BLP Diagnostics Checklist:**

• [ ] First-stage F > 10 for price instruments
• [ ] Run 10+ ra