pybhatlib 0.3.2__tar.gz → 0.4.0__tar.gz

{pybhatlib-0.3.2 → pybhatlib-0.4.0}/.gitignore

@@ -70,3 +70,12 @@ PESOSE-related
 .env
 .claude
 
+pesose*
+
+# Local scratch / harness output (mixed-model work)
+issue*
+PR32*
+0714*
+0717*
+gauss_harness/
+bench/*_log.csv

{pybhatlib-0.3.2 → pybhatlib-0.4.0}/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable changes to pybhatlib are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-09-16
+
+### Added
+- **Linear regression (LR)** — `LRModel` / `LRControl` / `LRResults`: one
+  continuous outcome solved in closed form (SVD least squares) with classical,
+  White-robust, and BHHH standard errors; the residual standard deviation
+  `sigma` is reported as the trailing parameter (MDCEV convention);
+  `lr_predict`, `lr_ate` / `lr_ate_from_params` on the shared `scenarios=`
+  API; tutorial `t09a_lr`.
+- **Mixed (simulation-based) model family** — a shared maximum-simulated-
+  likelihood engine (Halton draws, panel broadcast, normal / log-normal /
+  Yeo-Johnson coefficient transforms, analytic scores through the
+  reparameterisation Jacobians), plus four models built on it:
+  `MixMNLModel` (mixed multinomial logit), `MNPKerCPModel` (mixed MNP
+  coupling random coefficients to the kernel error through a copula),
+  `MORPFlexModel` (mixed MORP with a flexible Yeo-Johnson
+  kernel and rectangle MVNCD), and `MDCEVMixedModel` (mixed MDCEV with a
+  vectorized per-draw kernel). These are new and still under active
+  refinement; the closed-form models above are the stable API.
+
+### Fixed
+- **MNP mixture-of-normals** — coefficients that are not random now stay shared
+  across segments instead of being re-estimated per segment.
+
 ## [0.3.2] - 2026-07-22
 
 First version available on PyPI. Identical in code to 0.3.1; released under a new

{pybhatlib-0.3.2 → pybhatlib-0.4.0}/PKG-INFO

@@ -1,7 +1,7 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: pybhatlib
-Version: 0.3.2
-Summary: Python implementation of BHATLIB: matrix-based inference for advanced econometric models
+Version: 0.4.0
+Summary: Matrix-based econometric inference in Python: analytic MVNCD evaluation and discrete-choice models
 Project-URL: Homepage, https://github.com/UMN-Choi-Lab/pybhatlib
 Project-URL: Repository, https://github.com/UMN-Choi-Lab/pybhatlib
 Project-URL: Documentation, https://github.com/UMN-Choi-Lab/pybhatlib#readme
@@ -40,18 +40,28 @@ Description-Content-Type: text/markdown
 
 # pybhatlib
 
+[![PyPI](https://img.shields.io/pypi/v/pybhatlib)](https://pypi.org/project/pybhatlib/)
 [![Python](https://img.shields.io/pypi/pyversions/pybhatlib)](https://pypi.org/project/pybhatlib/)
+[![Tests](https://img.shields.io/github/actions/workflow/status/UMN-Choi-Lab/pybhatlib/tests.yml?branch=main&label=tests)](https://github.com/UMN-Choi-Lab/pybhatlib/actions/workflows/tests.yml)
 [![License: MIT](https://img.shields.io/pypi/l/pybhatlib)](https://github.com/UMN-Choi-Lab/pybhatlib/blob/main/LICENSE)
 
-Python reimplementation of **BHATLIB** — an open-source library for statistical and
-econometric matrix-based inference methods.
+Open-source Python library for matrix-based econometric inference: multivariate
+normal CDF evaluation with analytic gradients, and maximum-likelihood estimation of
+discrete-choice models (MNP, MORP, MDCEV, MNL).
 
-BHATLIB (Bhat, Clower, Haddad, Jones; UT Austin / Aptech Systems) provides efficient
-matrix operations, gradient-enabled routines for multivariate distribution evaluation
-(including Bhat's 2018 MVNCD analytic approximation), and pre-built econometric models.
+The numerical core follows the GAUSS **BHATLIB** library by Chandra Bhat and
+colleagues (UT Austin / Aptech Systems) and implements Bhat's (2018) analytic
+MVNCD approximation.
 
 ## Installation
 
+```bash
+pip install pybhatlib                  # core (NumPy + SciPy + Numba)
+pip install "pybhatlib[torch]"         # add PyTorch backend (optional GPU)
+```
+
+From source (for development, or to run the bundled examples and tutorials):
+
 ```bash
 git clone https://github.com/UMN-Choi-Lab/pybhatlib.git
 cd pybhatlib
@@ -117,8 +127,15 @@ A runnable end-to-end example (with `morp_ate`, `morp_predict`,
 - **Multivariate Ordered Response Probit (MORP)** — multiple ordinal outcomes
   with shared covariance; per-outcome `spec` mapping
 - **Multiple Discrete-Continuous Extreme Value (MDCEV)** — traditional
-  (Bhat 2008) and linear (Bhat 2018) outside-good utility specifications,
-  selected via `MDCEVControl.utility`
+  (Bhat 2008) and linear outside-good utility specifications, selected via
+  `MDCEVControl.utility`
+- **Multinomial Logit (MNL)**
+- **Linear regression (LR)** — single continuous outcome, closed-form OLS with
+  classical / White-robust / BHHH standard errors
+- **Mixed / simulation-based models** — `MixMNLModel`, `MNPKerCPModel`,
+  `MORPFlexModel`, `MDCEVMixedModel` on a shared maximum-simulated-likelihood
+  engine (Halton draws, panel data, normal / log-normal / Yeo-Johnson
+  coefficient transforms). New and under active refinement.
 
 **Numerical core**
 - `vecup` — vecdup, matdupfull, LDLT decomposition, truncated MVN moments
@@ -151,8 +168,8 @@ A runnable end-to-end example (with `morp_ate`, `morp_predict`,
 
 ## Verification
 
-pybhatlib reproduces Table 1 from the BHATLIB paper (Bhat 2018) using the
-TRAVELMODE dataset (3 modes — DA, SR, TR; 1125 observations):
+pybhatlib reproduces Table 1 of the BHATLIB GAUSS reference implementation using
+the TRAVELMODE dataset (3 modes — DA, SR, TR; 1125 observations):
 
 | Model | Specification | Target LL | Achieved LL | Status |
 |-------|--------------|-----------|-------------|--------|
@@ -162,10 +179,10 @@ TRAVELMODE dataset (3 modes — DA, SR, TR; 1125 observations):
 | (c)     | + Random coeff. OVTT        | -635.871 | -635.871 | exact match |
 | (d)     | 2-segment mixture           | -634.975 | -632.912 | close (multi-modal) |
 
-Models (a)–(c) reproduce the published estimates and BHHH standard errors to
-≤0.001 on every parameter (verified end-to-end against GAUSS 26.1.1 + MaxLik
-5.0.9). Model (d) is documented as multi-modal — the Python optimum is a
-slightly better local mode than the published one.
+Models (a)–(c) reproduce the GAUSS estimates and BHHH standard errors to ≤0.001
+on every parameter (verified end-to-end against GAUSS 26.1.1 + MaxLik 5.0.9).
+Model (d) is multi-modal — the Python optimum is a slightly better local mode
+than the GAUSS one.
 
 For MORP, `iid=False` now uses GAUSS BHATLIB's unit-variance identification by
 default (`MORPControl.fix_scales=True`): the latent-utility variances are fixed
@@ -193,6 +210,8 @@ matching `.py` script under `python_scripts/`):
 | MNP | `t04a_mnp_iid` … `t04g_mnp_forecasting`, `t04h_bhatlib_table1`, `t04i_bhat2018_table2` |
 | MORP | `t05b_morp_ate_predict` |
 | MDCEV | `t07a_mdcev_trad`, `t07b_mdcev_lin` |
+| MNL | `t08a_mnl` |
+| LR | `t09a_lr` |
 | Backends & verification | `t06a_backend_switching`, `t06b_custom_specs`, `t06c_gradient_verification` |
 
 ## Contributing
@@ -211,8 +230,9 @@ pytest tests/ -m torch        # PyTorch backend tests only
 1. Bhat, C. R. (2018). New Matrix-Based Methods for the Analytic Evaluation of the
    Multivariate Cumulative Normal Distribution Function. *Transportation Research
    Part B*, 109: 238–256.
-2. Bhat, C. R., Clower, E., Haddad, A. J., Jones, J. BHATLIB: An Open-Source
-   Library for Statistical and Econometric Matrix-Based Inference Methods in GAUSS.
+2. Bhat, C. R. (2008). The Multiple Discrete-Continuous Extreme Value (MDCEV)
+   Model: Role of Utility Function Parameters, Identification Considerations, and
+   Model Extensions. *Transportation Research Part B*, 42(3): 274–303.
 
 ## License
 

{pybhatlib-0.3.2 → pybhatlib-0.4.0}/README.md

@@ -1,17 +1,27 @@
 # pybhatlib
 
+[![PyPI](https://img.shields.io/pypi/v/pybhatlib)](https://pypi.org/project/pybhatlib/)
 [![Python](https://img.shields.io/pypi/pyversions/pybhatlib)](https://pypi.org/project/pybhatlib/)
+[![Tests](https://img.shields.io/github/actions/workflow/status/UMN-Choi-Lab/pybhatlib/tests.yml?branch=main&label=tests)](https://github.com/UMN-Choi-Lab/pybhatlib/actions/workflows/tests.yml)
 [![License: MIT](https://img.shields.io/pypi/l/pybhatlib)](https://github.com/UMN-Choi-Lab/pybhatlib/blob/main/LICENSE)
 
-Python reimplementation of **BHATLIB** — an open-source library for statistical and
-econometric matrix-based inference methods.
+Open-source Python library for matrix-based econometric inference: multivariate
+normal CDF evaluation with analytic gradients, and maximum-likelihood estimation of
+discrete-choice models (MNP, MORP, MDCEV, MNL).
 
-BHATLIB (Bhat, Clower, Haddad, Jones; UT Austin / Aptech Systems) provides efficient
-matrix operations, gradient-enabled routines for multivariate distribution evaluation
-(including Bhat's 2018 MVNCD analytic approximation), and pre-built econometric models.
+The numerical core follows the GAUSS **BHATLIB** library by Chandra Bhat and
+colleagues (UT Austin / Aptech Systems) and implements Bhat's (2018) analytic
+MVNCD approximation.
 
 ## Installation
 
+```bash
+pip install pybhatlib                  # core (NumPy + SciPy + Numba)
+pip install "pybhatlib[torch]"         # add PyTorch backend (optional GPU)
+```
+
+From source (for development, or to run the bundled examples and tutorials):
+
 ```bash
 git clone https://github.com/UMN-Choi-Lab/pybhatlib.git
 cd pybhatlib
@@ -77,8 +87,15 @@ A runnable end-to-end example (with `morp_ate`, `morp_predict`,
 - **Multivariate Ordered Response Probit (MORP)** — multiple ordinal outcomes
   with shared covariance; per-outcome `spec` mapping
 - **Multiple Discrete-Continuous Extreme Value (MDCEV)** — traditional
-  (Bhat 2008) and linear (Bhat 2018) outside-good utility specifications,
-  selected via `MDCEVControl.utility`
+  (Bhat 2008) and linear outside-good utility specifications, selected via
+  `MDCEVControl.utility`
+- **Multinomial Logit (MNL)**
+- **Linear regression (LR)** — single continuous outcome, closed-form OLS with
+  classical / White-robust / BHHH standard errors
+- **Mixed / simulation-based models** — `MixMNLModel`, `MNPKerCPModel`,
+  `MORPFlexModel`, `MDCEVMixedModel` on a shared maximum-simulated-likelihood
+  engine (Halton draws, panel data, normal / log-normal / Yeo-Johnson
+  coefficient transforms). New and under active refinement.
 
 **Numerical core**
 - `vecup` — vecdup, matdupfull, LDLT decomposition, truncated MVN moments
@@ -111,8 +128,8 @@ A runnable end-to-end example (with `morp_ate`, `morp_predict`,
 
 ## Verification
 
-pybhatlib reproduces Table 1 from the BHATLIB paper (Bhat 2018) using the
-TRAVELMODE dataset (3 modes — DA, SR, TR; 1125 observations):
+pybhatlib reproduces Table 1 of the BHATLIB GAUSS reference implementation using
+the TRAVELMODE dataset (3 modes — DA, SR, TR; 1125 observations):
 
 | Model | Specification | Target LL | Achieved LL | Status |
 |-------|--------------|-----------|-------------|--------|
@@ -122,10 +139,10 @@ TRAVELMODE dataset (3 modes — DA, SR, TR; 1125 observations):
 | (c)     | + Random coeff. OVTT        | -635.871 | -635.871 | exact match |
 | (d)     | 2-segment mixture           | -634.975 | -632.912 | close (multi-modal) |
 
-Models (a)–(c) reproduce the published estimates and BHHH standard errors to
-≤0.001 on every parameter (verified end-to-end against GAUSS 26.1.1 + MaxLik
-5.0.9). Model (d) is documented as multi-modal — the Python optimum is a
-slightly better local mode than the published one.
+Models (a)–(c) reproduce the GAUSS estimates and BHHH standard errors to ≤0.001
+on every parameter (verified end-to-end against GAUSS 26.1.1 + MaxLik 5.0.9).
+Model (d) is multi-modal — the Python optimum is a slightly better local mode
+than the GAUSS one.
 
 For MORP, `iid=False` now uses GAUSS BHATLIB's unit-variance identification by
 default (`MORPControl.fix_scales=True`): the latent-utility variances are fixed
@@ -153,6 +170,8 @@ matching `.py` script under `python_scripts/`):
 | MNP | `t04a_mnp_iid` … `t04g_mnp_forecasting`, `t04h_bhatlib_table1`, `t04i_bhat2018_table2` |
 | MORP | `t05b_morp_ate_predict` |
 | MDCEV | `t07a_mdcev_trad`, `t07b_mdcev_lin` |
+| MNL | `t08a_mnl` |
+| LR | `t09a_lr` |
 | Backends & verification | `t06a_backend_switching`, `t06b_custom_specs`, `t06c_gradient_verification` |
 
 ## Contributing
@@ -171,8 +190,9 @@ pytest tests/ -m torch        # PyTorch backend tests only
 1. Bhat, C. R. (2018). New Matrix-Based Methods for the Analytic Evaluation of the
    Multivariate Cumulative Normal Distribution Function. *Transportation Research
    Part B*, 109: 238–256.
-2. Bhat, C. R., Clower, E., Haddad, A. J., Jones, J. BHATLIB: An Open-Source
-   Library for Statistical and Econometric Matrix-Based Inference Methods in GAUSS.
+2. Bhat, C. R. (2008). The Multiple Discrete-Continuous Extreme Value (MDCEV)
+   Model: Role of Utility Function Parameters, Identification Considerations, and
+   Model Extensions. *Transportation Research Part B*, 42(3): 274–303.
 
 ## License
 

{pybhatlib-0.3.2 → pybhatlib-0.4.0}/examples/tutorials/python_scripts/t04e_mnp_mixture.py

@@ -80,7 +80,8 @@ print("""
   Example (S=2, n_beta=7, flexible covariance with 1 free param):
       2 * 7  +  1  +  1  =  16 parameters
 
-  In pybhatlib: set nseg=2 in MNPControl to enable a 2-segment mixture.
+  In pybhatlib: set nseg=2 in MNPControl and name the coefficient(s) that
+  vary by segment in ranvars=[...]; every other coefficient is shared.
 """)
 
 # ============================================================
@@ -110,6 +111,7 @@ model = MNPModel(
     alternatives=alternatives,
     spec=spec,
     control=MNPControl(iid=False, nseg=2, maxiter=200, verbose=1, seed=42),
+    ranvars=["OVTT"],   # OVTT varies by segment; all other betas are shared
 )
 results = model.fit()
 t_elapsed = time.perf_counter() - t0
@@ -149,15 +151,13 @@ print("""
     "MNP Table2 d") fits a 2-segment mixture WITH a random coefficient
     on OVTT (ranvars=["OVTT"], nrand=1), reaching LL = -634.975.
 
-    This tutorial uses the simpler segment-specific-means form (nseg=2
-    with no random coefficient inside each segment).  On the supplied
-    TRAVELMODE data this reaches LL = -632.912 — slightly HIGHER (better)
-    than the paper target because it has a different parameterization and
-    one fewer covariance restriction.  This is expected: mixture models
-    have many local optima, and a higher LL simply means the optimizer
-    found a better mode of this likelihood surface.  To reproduce the
-    exact paper model, add ranvars=["OVTT"] to the MNPModel(...) call
-    (see Step 4).
+    That is exactly the model fitted above: only OVTT gets a
+    segment-specific coefficient (and its own variance) in each segment,
+    every other coefficient is shared across the two segments, and the
+    kernel covariance is common.  On the supplied TRAVELMODE data
+    pybhatlib reaches LL = -634.94, matching the paper to 0.04.  Mixture
+    likelihoods have several local optima, so a different seed may stop
+    at a slightly different mode with a similar LL.
 """)
 
 # Print segment probabilities if available
@@ -180,10 +180,12 @@ print("""
   two segments' coefficient vectors side by side and weight them by the
   estimated mixing probabilities pi_s.
 
-  In this 7-variable specification, the segment-1 betas are the first 7
-  entries of b_original (CON_SR..COST) and the segment-2 betas are the
-  *_s2 entries near the end.  Reading them together tells us how the two
-  groups differ in their sensitivity to travel time and cost.
+  In this 7-variable specification only OVTT was allowed to vary by
+  segment (ranvars=["OVTT"]), so segment 1 owns the first 7 entries of
+  b_original (CON_SR..COST) and segment 2 differs from it only in the
+  OVTT_s2 entry near the end; the other six coefficients are shared and
+  identical in both columns below.  Reading OVTT across the two groups
+  tells us how they differ in out-of-vehicle time sensitivity.
 """)
 
 # Pair up segment-1 and segment-2 betas for the 7 utility variables.
@@ -196,7 +198,7 @@ print(f"  {'Variable':<12s}{'Seg1 beta':>12s}{'Seg2 beta':>12s}"
 print("  " + "-" * 49)
 for nm in beta_names:
     b1 = name_to_val.get(nm, float("nan"))
-    b2 = name_to_val.get(nm + "_s2", float("nan"))
+    b2 = name_to_val.get(nm + "_s2", b1)   # shared coefficient -> same value
     mixed = pi[0] * b1 + pi[1] * b2
     print(f"  {nm:<12s}{b1:>12.4f}{b2:>12.4f}{mixed:>13.4f}")
 
@@ -247,12 +249,15 @@ print("""
 
           for seed in [42, 123, 456, 789]:
               ctrl = MNPControl(iid=False, nseg=2, seed=seed, maxiter=200)
-              res  = MNPModel(..., control=ctrl).fit()
+              res  = MNPModel(..., control=ctrl, ranvars=["OVTT"]).fit()
               print(seed, res.loglik * res.n_obs)
 
-  Parameter count scaling:
-    - nseg=2: 2 * n_beta + 1 segment param + n_cov  (doubles the betas)
-    - nseg=3: 3 * n_beta + 2 segment params + n_cov  (triples the betas)
+  Parameter count scaling (n_rand = number of names in ranvars):
+    - nseg=1: n_beta + n_cov + n_omega(n_rand)
+    - nseg=2: + 1 segment param + n_rand betas + n_omega(n_rand)
+    - nseg=3: + 2 segment params + 2 * (n_rand betas + n_omega(n_rand))
+    Coefficients not listed in ranvars are shared across segments and
+    cost nothing extra.
     - Identification requires sufficient variation in the data; too many
       segments on a small dataset will produce near-flat likelihood
 
@@ -263,7 +268,7 @@ print("""
     4. Use LR test or BIC to decide between nseg=1 and nseg=2
 
   Rule of thumb:
-    - Each additional segment adds n_beta + 1 free parameters
+    - Each additional segment adds 1 + n_rand + n_omega(n_rand) free parameters
     - Worthwhile only when delta-LL > (n_beta + 1) / 2  (BIC criterion)
     - For n_beta=7: need delta-LL > 4  to justify a second segment
 """)

{pybhatlib-0.3.2 → pybhatlib-0.4.0}/examples/tutorials/python_scripts/t04h_bhatlib_table1.py

@@ -320,6 +320,7 @@ model_d = MNPModel(
     alternatives=alternatives,
     spec=spec_7var,
     control=MNPControl(iid=False, nseg=2, maxiter=200, verbose=0, seed=42),
+    ranvars=["OVTT"],   # paper Model (d): OVTT varies by segment
 )
 res_d = model_d.fit()
 t_d = time.perf_counter() - t0

pybhatlib-0.4.0/examples/tutorials/python_scripts/t09a_lr.py

@@ -0,0 +1,238 @@
+"""Tutorial T09a: Linear Regression (Single Continuous Outcome).
+
+This tutorial fits an ordinary least-squares linear regression with
+pybhatlib's ``LRModel`` on the tourism-expenditure data used in t07a/t07b,
+explaining log total trip expenditure with traveller and trip attributes.
+
+What you will learn:
+  - How the ``spec`` convention shared by all pybhatlib models maps
+    coefficient names to data columns (``"uno"`` = constant)
+  - That estimation is analytical (SVD least squares): no optimizer,
+    starting values, or convergence settings
+  - How to read ``results.summary()``: coefficient table with the
+    residual standard deviation ``sigma`` as the trailing parameter,
+    R-squared, F-test, residual variance
+  - How ``LRControl(se_method=...)`` switches between classical,
+    heteroscedasticity-robust (White), and BHHH standard errors
+  - Prediction on the training data or on a new DataFrame
+  - Average treatment effects via the ``scenarios=`` API shared with
+    MNP / MNL / MORP / MDCEV, and ATEs from externally supplied coefficients
+
+Prerequisites: t00 (quickstart).
+
+Expected runtime: < 1 sec
+"""
+import os, sys
+import numpy as np
+import pandas as pd
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", "..", "src"))
+
+from pybhatlib.models.lr import LRControl, LRModel, lr_ate_from_params
+
+data_path = os.path.join(os.path.dirname(__file__), "..", "..", "data", "WorkshopData_ToursimExp.csv")
+
+# ============================================================
+#  Step 1: Data and Specification
+# ============================================================
+print("=" * 60)
+print("  Step 1: Data and Specification")
+print("=" * 60)
+
+data = pd.read_csv(data_path)
+
+# Outcome: log of total trip expenditure across the five spending categories
+# (accommodation, food & beverage, transport, shopping, recreation).
+data["total_exp"] = data[["Accomod", "FandB", "Transp", "Shp", "Recr"]].sum(axis=1)
+data["ln_exp"] = np.log(data["total_exp"])
+
+print(f"  n = {len(data)} trips")
+print(f"  total expenditure: mean = {data['total_exp'].mean():,.0f}, "
+      f"median = {data['total_exp'].median():,.0f}")
+print(f"  ln_exp: mean = {data['ln_exp'].mean():.3f}, sd = {data['ln_exp'].std():.3f}")
+
+print("""
+  The spec grammar is the one every pybhatlib model uses: a coefficient
+  name maps to a data column, to "uno" (a column of ones, i.e. the
+  constant), or to a numeric constant. Nothing is added implicitly, so
+  the intercept is declared explicitly. The outcome-keyed form used by
+  the multi-outcome models, e.g. {"B_RURAL": {"ln_exp": "rural"}}, is
+  also accepted.
+""")
+
+spec = {
+    "CON":      "uno",      # constant
+    "B_RURAL":  "rural",    # rural residence (urban = base)
+    "B_FEM":    "fr_fem",   # fraction of the travel party that is female
+    "B_HINC":   "hinc20k",  # household income above $20k
+    "B_ST410":  "st410",    # stay of 4-10 days (< 3 days = base)
+    "B_STGT10": "stgt10",   # stay longer than 10 days
+}
+
+for name, col in spec.items():
+    print(f"  {name:<10s} <- {col}")
+
+# ============================================================
+#  Step 2: Estimate and Summarize
+# ============================================================
+print("\n" + "=" * 60)
+print("  Step 2: Estimate and Summarize")
+print("=" * 60)
+
+print("""
+  LRModel follows the same object surface as the other models
+  (fit / predict / ate / results.summary()), but the least-squares
+  solution is computed in closed form from the SVD of the design
+  matrix. There is no optimizer, so LRControl carries only covariance
+  and verbosity options; results.n_iter is 0 and results.converged is
+  True by construction.
+""")
+
+model = LRModel(
+    data=data,
+    dep_var="ln_exp",
+    spec=spec,
+    control=LRControl(verbose=1),
+)
+results = model.fit()
+print()
+results.summary()
+
+print("""
+  Reading the summary:
+    - The last row, sigma, is the residual standard deviation: the
+      Gaussian MLE sqrt(SSE / N), reported as a parameter with its own
+      standard error exactly as MDCEV reports its scale (results.params
+      is [coefficients..., sigma]). Its t-statistic tests sigma = 0 and
+      carries no information.
+    - Mean log-likelihood is the Gaussian log-likelihood per observation
+      at sigma^2 = SSE / N (results.sigma2).
+    - Residual variance is the unbiased SSE / (N - K)
+      (results.residual_variance); the default se_method="hessian" with
+      df_correction=True gives the textbook OLS covariance
+      SSE / (N - K) * (X'X)^-1 for the coefficients. p-values use
+      Student's t with N - K degrees of freedom for every se_method.
+    - F(df_model, df_resid) jointly tests all non-constant slopes.
+    - R-squared is centered because the design spans a constant.
+""")
+
+print("  Coefficient table as a DataFrame:")
+print(results.to_dataframe().round(4).to_string())
+
+# ============================================================
+#  Step 3: Standard-Error Options
+# ============================================================
+print("\n" + "=" * 60)
+print("  Step 3: Standard-Error Options")
+print("=" * 60)
+
+print("""
+  Expenditure data are typically heteroscedastic, so compare the
+  classical covariance with the White sandwich. With df_correction=True
+  (the default) the sandwich is the HC1 form; "bhhh" inverts the score
+  cross-product of the Gaussian likelihood over all parameters including
+  sigma. Estimates are identical across methods; only the standard
+  errors change.
+""")
+
+se_table = {}
+for method in ["hessian", "sandwich", "bhhh"]:
+    ctrl = LRControl(se_method=method, verbose=0)
+    se_table[method] = LRModel(data, "ln_exp", spec, control=ctrl).fit().se
+
+print(f"  {'coef':<10s} {'estimate':>10s} {'se hessian':>12s} {'se sandwich':>12s} {'se bhhh':>10s}")
+print("  " + "-" * 58)
+for k, name in enumerate(results.param_names):
+    print(f"  {name:<10s} {results.params[k]:>10.4f} {se_table['hessian'][k]:>12.4f} "
+          f"{se_table['sandwich'][k]:>12.4f} {se_table['bhhh'][k]:>10.4f}")
+
+# ============================================================
+#  Step 4: Prediction
+# ============================================================
+print("\n" + "=" * 60)
+print("  Step 4: Prediction")
+print("=" * 60)
+
+print("""
+  model.predict() with no argument returns the in-sample fitted values.
+  Passing a DataFrame rebuilds the design through the model's spec, so
+  new observations only need the columns the spec refers to. (Passing a
+  ready-made (N, K) array is also accepted.)
+""")
+
+y_hat = model.predict()
+rmse = np.sqrt(np.mean((data["ln_exp"] - y_hat) ** 2))
+print(f"  In-sample RMSE of ln_exp: {rmse:.4f}")
+print(f"  R-squared recomputed from fitted values: "
+      f"{1 - np.sum((data['ln_exp'] - y_hat) ** 2) / np.sum((data['ln_exp'] - data['ln_exp'].mean()) ** 2):.6f}")
+
+new_trips = pd.DataFrame({
+    "rural":   [0, 1],
+    "fr_fem":  [0.5, 0.5],
+    "hinc20k": [1, 0],
+    "st410":   [1, 0],
+    "stgt10":  [0, 1],
+})
+pred_ln = model.predict(new_trips)
+print("\n  Two hypothetical trips:")
+print(f"  {'trip':<6s} {'rural':>6s} {'hinc':>5s} {'stay':>8s} {'ln_exp':>8s} {'exp(ln_exp)':>12s}")
+for i in range(len(new_trips)):
+    stay = "4-10 d" if new_trips.st410[i] else (">10 d" if new_trips.stgt10[i] else "<3 d")
+    print(f"  {i + 1:<6d} {new_trips.rural[i]:>6d} {new_trips.hinc20k[i]:>5d} {stay:>8s} "
+          f"{pred_ln[i]:>8.3f} {np.exp(pred_ln[i]):>12,.0f}")
+
+print("""
+  Note: exp(predicted ln_exp) is the conditional median-type prediction
+  of expenditure, not its conditional mean (Jensen's inequality).
+""")
+
+# ============================================================
+#  Step 5: Average Treatment Effects (scenarios= API)
+# ============================================================
+print("\n" + "=" * 60)
+print("  Step 5: Average Treatment Effects (scenarios= API)")
+print("=" * 60)
+
+print("""
+  model.ate(scenarios=...) uses the scenario grammar shared with the other
+  models: each scenario overrides data columns with a scalar or with
+  another column, the design is rebuilt through the spec, and the mean
+  prediction is reported per scenario. For a linear model the effect in
+  outcome units of switching a dummy from 0 to 1 is exactly its
+  coefficient, which makes this a good check of the machinery.
+""")
+
+ate = model.ate(scenarios={
+    "urban": {"rural": 0},
+    "rural": {"rural": 1},
+    "long_stay_hinc": {"st410": 0, "stgt10": 1, "hinc20k": 1},
+})
+ate.summary()
+
+effect_units = ate.comparison("urban", "rural")
+print(f"\n  ATE rural vs urban, in ln_exp units:  {effect_units:+.4f}")
+print(f"  B_RURAL coefficient:                  {results.params[1]:+.4f}")
+print(f"  Implied expenditure ratio exp(B):     {np.exp(results.params[1]):.3f}")
+
+print("""
+  comparison() reports the effect in outcome units (here ln_exp).
+  percent=True gives the percentage change of the *predicted mean of
+  ln_exp*, the share-model convention; for a log outcome that is not the
+  percentage change in expenditure. Use exp(effect) - 1 for that, as
+  shown above.
+""")
+
+print("  Scenario table:")
+print(ate.to_dataframe().round(4).to_string())
+
+# ATEs from externally supplied estimates (e.g. GAUSS output) without
+# re-fitting: pass the reported vector [coefficients..., sigma] exactly as
+# printed by summary(); same scenario API, same numbers.
+external = lr_ate_from_params(
+    results.params,
+    param_names=results.param_names,
+    data=data, spec=spec, dep_var="ln_exp",
+    scenarios={"urban": {"rural": 0}, "rural": {"rural": 1}},
+)
+print(f"\n  lr_ate_from_params reproduces the fitted ATE: "
+      f"{external.comparison('urban', 'rural'):+.4f}")