pybhatlib 0.3.1__tar.gz → 0.4.0__tar.gz

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

@@ -28,10 +28,18 @@ htmlcov/
 *.dat
 *.pkl
 *.pdf
+*.tar.gz
 results/
+experiments/
+pr32-*.md
 
 # Original GAUSS source
 chandra_code/
+UTAcode_0402/
+slides/
+docs/
+Gauss Files and Comparison/
+anna0605/
 
 # Project-local docs (not for repo)
 CLAUDE.md
@@ -55,3 +63,19 @@ nul
 *.fdb_latexmk
 *.fls
 *.synctex.gz
+
+# PESOSE proposal working files — internal, NOT for the (soon-public) repo
+PESOSE_*
+PESOSE-related
+.env
+.claude
+
+pesose*
+
+# Local scratch / harness output (mixed-model work)
+issue*
+PR32*
+0714*
+0717*
+gauss_harness/
+bench/*_log.csv

pybhatlib-0.4.0/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+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
+patch number only because 0.3.1's filenames had already been reserved on PyPI (an
+earlier 0.3.1 upload was deleted, and PyPI never permits reusing a deleted
+filename). See the 0.3.1 entry below for the full feature list.
+
+## [0.3.1] - 2026-07-22
+
+Prepared as the first PyPI release but withdrawn before general availability; never
+installable from PyPI. Superseded by 0.3.2 (same code). Contents:
+
+### Models
+- **Multinomial Probit (MNP)** — IID, flexible covariance, heteroscedastic-only,
+  random coefficients, and mixture-of-normals specifications.
+- **Multivariate Ordered Response Probit (MORP)** — multiple ordinal outcomes
+  with shared covariance and per-outcome `spec` mapping.
+- **Multiple Discrete-Continuous Extreme Value (MDCEV)** — traditional
+  (Bhat 2008) and linear (Bhat 2018) outside-good utility specifications.
+- **Multinomial Logit (MNL)**.
+
+### Numerical core
+- `vecup` — vecdup, matdupfull, LDLT decomposition, truncated MVN moments.
+- `matgradient` — gradcovcor, gomegxomegax, spherical / Cholesky parameterizations.
+- `gradmvn` — Bhat (2018) MVNCD analytic approximation with analytic gradients.
+
+### Estimation & post-estimation
+- BHHH / Hessian / sandwich standard-error estimators, computed at fit time.
+- Average Treatment Effects (ATE) with scenario-matrix support, forecasting,
+  per-category MORP probability prediction, and ATEs computed directly from
+  supplied coefficients without re-fitting.
+- Optional PyTorch backend (`pip install pybhatlib[torch]`) with GPU support;
+  all numerical functions accept an optional `xp` backend kwarg.
+
+### Verification
+- Reproduces Table 1 of Bhat (2018) on the TRAVELMODE dataset: models (a)-(c)
+  match published log-likelihoods and BHHH standard errors to =0.001; model (d)
+  is documented as multi-modal.
+
+[0.3.2]: https://github.com/UMN-Choi-Lab/pybhatlib/releases/tag/v0.3.2
+[0.3.1]: https://github.com/UMN-Choi-Lab/pybhatlib/releases/tag/v0.3.1

pybhatlib-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,188 @@
+# Contributing to pybhatlib
+
+Thanks for your interest in contributing. This guide covers the pull request
+workflow, local development setup, and the standards we maintain for
+numerical correctness. It is written to be usable even if you are new to
+GitHub — read top to bottom the first time.
+
+## Quick overview
+
+- All changes go through a **pull request (PR)** — nobody pushes directly to `main`.
+- Each PR covers **one logical change**, not a batch of unrelated edits.
+- CI runs `pytest` automatically on every PR. **CI must pass before merging.**
+- Because pybhatlib reproduces published log-likelihood values exactly, any
+  change that alters numerical results must be justified and verified.
+
+## Setting up locally
+
+```bash
+git clone https://github.com/UMN-Choi-Lab/pybhatlib.git
+cd pybhatlib
+pip install -e ".[dev]"
+```
+
+Verify the install:
+
+```bash
+pytest tests/ -m "not slow"
+```
+
+All tests should pass. If they do not, open an issue before making changes —
+something in your environment is off, and PRs built on a broken baseline
+waste review time.
+
+## The pull request workflow
+
+### 1. Create a branch
+
+One branch per logical change. Short, descriptive names — not your username,
+not a date.
+
+```bash
+git checkout main
+git pull origin main
+git checkout -b fix-mixture-shared-coefs
+```
+
+Good branch names: `fix-mixture-shared-coefs`, `add-mvncd-j5-benchmark`,
+`docs-contributing-guide`.
+
+Avoid: `dales-changes`, `update`, `wip`, `patch-1`.
+
+### 2. Make changes and commit
+
+```bash
+# Edit files...
+pytest tests/ -m "not slow"        # Run tests before committing
+git add <files>
+git commit -m "Short imperative summary of the change"
+```
+
+If you touch a tutorial, edit the `.py` script under
+`examples/tutorials/python_scripts/` (the single source of truth) and
+regenerate the notebooks — the `notebooks` CI job fails if they are stale or
+missing:
+
+```bash
+python examples/tutorials/_convert_to_ipynb.py
+git add examples/tutorials/*.ipynb
+```
+
+Commit message style:
+
+- First line: imperative mood, under 72 characters
+  (`"Add shared-coefficient support for mixture-of-normals"`, not
+  `"Added ..."` or `"Changes to mixture"`).
+- Optional body after a blank line explains *why*, not *what*.
+- One commit per logical step is fine; squash trivial fixup commits before
+  pushing (`git rebase -i main`).
+
+### 3. Push and open the PR
+
+```bash
+git push -u origin fix-mixture-shared-coefs
+```
+
+GitHub prints a URL for opening the PR after the push — click it, or visit
+the repo on github.com and look for the "Compare & pull request" banner.
+
+PR description should cover:
+
+- **What** changed (one or two sentences).
+- **Why** the change is needed (link to an issue or email thread if relevant).
+- **How it was tested** — which tests you ran, which tutorials you re-executed,
+  any benchmark numbers.
+- **Verification impact** — if your change could affect log-likelihoods,
+  explicitly state whether you re-ran the Table 1 verification (see below).
+
+### 4. Review and merge
+
+A maintainer reviews the PR, may request changes, and merges it. While the
+PR is open:
+
+- Push new commits to the same branch — they update the PR automatically.
+- Do not force-push unless asked.
+- Do not merge `main` into your branch unless requested; rebase if you must
+  update.
+
+After merge, delete your branch:
+
+```bash
+git checkout main
+git pull origin main
+git branch -d fix-mixture-shared-coefs
+```
+
+## Numerical verification (important)
+
+pybhatlib reproduces exact log-likelihood values from BHATLIB Table 1:
+
+| Model | LL |
+|-------|-----|
+| (a)(i) IID | −670.956 |
+| (a)(ii) Flexible | −661.111 |
+| (b) + AGE45 | −659.285 |
+| (c) Random coefficient | −635.871 |
+| (d) Mixture (nseg=2) | ≈−634.975 |
+
+If your change touches any code under `src/pybhatlib/gradmvn/`,
+`src/pybhatlib/matgradient/`, `src/pybhatlib/vecup/`, or
+`src/pybhatlib/models/mnp/`, run the Table 1 tutorial locally before
+requesting review:
+
+```bash
+jupyter nbconvert --to notebook --execute examples/tutorials/t04h_bhatlib_table1.ipynb
+```
+
+Include the resulting LL values in the PR description. If they differ from
+the table, explain why the change is intentional — do not merge a regression
+without discussion.
+
+## Code standards
+
+- **Python**: PEP 8, 88-char line length (matches `ruff` config).
+- **Type hints** on all public function signatures.
+- **Docstrings** in NumPy style on all public functions.
+- **Backend-aware numerical code** accepts an optional `xp` keyword for
+  NumPy / PyTorch backend selection.
+- **Numba-compatible** in hot paths — use `scipy.special.ndtr`, not
+  `scipy.stats.norm.cdf`; avoid Python-level scipy.stats objects inside
+  JIT-compiled functions.
+- **No module-level mutable state** — thread safety matters for parallel
+  gradient evaluations.
+- **Private modules** are prefixed with an underscore (`_vec_ops.py`).
+
+## Running specific test subsets
+
+```bash
+pytest tests/                      # Everything including slow integration tests
+pytest tests/ -m "not slow"        # Skip slow tests (what CI runs)
+pytest tests/ -m torch             # Only PyTorch-backend tests (needs torch installed)
+pytest tests/test_models/          # Just the model tests
+pytest tests/ -k mnp               # Tests matching "mnp" in name
+```
+
+## Scope rules
+
+- **One logical change per PR.** Bundling a bug fix, a feature, and a refactor
+  into one PR makes review painful and makes `git bisect` useless if a
+  regression shows up later.
+- **Do not reformat unrelated code** in your PR. If you notice style issues
+  elsewhere, open a separate PR for cleanup.
+- **Performance changes need before/after numbers.** "Faster" is not
+  reviewable; "1.40s → 0.82s on Table 1 Model (a)(ii)" is.
+- **Feature additions that change model semantics** (e.g., allowing
+  coefficients to be shared across mixture segments) should include a test
+  that pins the new behavior.
+
+## Getting help
+
+- **Questions about an existing PR**: comment on the PR directly.
+- **Questions about where to start**: open an issue with the `question` label.
+- **Something is broken**: open an issue with a minimal reproducer and the
+  output of `pip freeze`.
+
+## License
+
+By contributing, you agree that your contributions are licensed under the
+MIT license (see `LICENSE`).

pybhatlib-0.4.0/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.5
+Name: pybhatlib
+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
+Project-URL: Issues, https://github.com/UMN-Choi-Lab/pybhatlib/issues
+Project-URL: Changelog, https://github.com/UMN-Choi-Lab/pybhatlib/blob/main/CHANGELOG.md
+Author-email: Seongjin Choi <choi@umn.edu>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: MVNCD,covariance matrix,discrete choice,econometrics,multinomial probit,transportation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+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 :: Mathematics
+Requires-Python: >=3.10
+Requires-Dist: numba>=0.59
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: scipy>=1.10
+Provides-Extra: all
+Requires-Dist: mypy; extra == 'all'
+Requires-Dist: pytest-cov; extra == 'all'
+Requires-Dist: pytest>=7.0; extra == 'all'
+Requires-Dist: ruff; extra == 'all'
+Requires-Dist: torch>=2.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: torch
+Requires-Dist: torch>=2.0; extra == 'torch'
+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)
+
+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).
+
+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
+pip install -e .                  # core (NumPy + SciPy + Numba)
+pip install -e ".[torch]"         # add PyTorch backend (optional GPU)
+pip install -e ".[dev]"           # add pytest, ruff, mypy
+pip install -e ".[all]"           # everything (torch + dev)
+```
+
+## Quick Start — Multinomial Probit (MNP)
+
+Sample data: `examples/data/TRAVELMODE.csv` (3 modes — DA / SR / TR, 1125 observations).
+
+```python
+from pybhatlib.models.mnp import MNPModel, MNPControl
+
+model = MNPModel(
+    data="examples/data/TRAVELMODE.csv",
+    alternatives=["Alt1_ch", "Alt2_ch", "Alt3_ch"],
+    availability="none",
+    spec={
+        "CON_SR": {"Alt1_ch": "sero", "Alt2_ch": "uno",     "Alt3_ch": "sero"},
+        "CON_TR": {"Alt1_ch": "sero", "Alt2_ch": "sero",    "Alt3_ch": "uno"},
+        "IVTT":   {"Alt1_ch": "IVTT_DA", "Alt2_ch": "IVTT_SR", "Alt3_ch": "IVTT_TR"},
+        "OVTT":   {"Alt1_ch": "OVTT_DA", "Alt2_ch": "OVTT_SR", "Alt3_ch": "OVTT_TR"},
+        "COST":   {"Alt1_ch": "COST_DA", "Alt2_ch": "COST_SR", "Alt3_ch": "COST_TR"},
+    },
+    control=MNPControl(iid=True),
+)
+results = model.fit()
+results.summary()
+```
+
+## Quick Start — Multivariate Ordered Response Probit (MORP)
+
+```python
+from pybhatlib.models.morp import MORPModel, MORPControl
+
+model = MORPModel(
+    data=df,                                     # DataFrame or CSV path
+    dep_vars=["satisfaction", "recommendation"], # ordinal outcome columns
+    spec={
+        "income":    {"satisfaction": "income",    "recommendation": "income"},
+        "age":       {"satisfaction": "age",       "recommendation": "age"},
+        "education": {"satisfaction": "education", "recommendation": "education"},
+    },
+    n_categories=[3, 3],
+    control=MORPControl(iid=True, seed=42),
+)
+results = model.fit()
+results.summary()
+```
+
+A runnable end-to-end example (with `morp_ate`, `morp_predict`,
+`morp_predict_category`) is at
+[`examples/tutorials/t05b_morp_ate_predict.ipynb`](https://github.com/UMN-Choi-Lab/pybhatlib/blob/main/examples/tutorials/t05b_morp_ate_predict.ipynb).
+
+## Features
+
+**Models**
+- **Multinomial Probit (MNP)** — IID, flexible covariance, heteroscedastic-only,
+  random coefficients, mixture-of-normals
+- **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 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
+- `matgradient` — gradcovcor, gomegxomegax, spherical / Cholesky parameterizations
+- `gradmvn` — Bhat (2018) MVNCD analytic approximation with analytic gradients
+
+**Estimation**
+- Multiple SE estimators (`se_method="bhhh" | "hessian" | "sandwich"`); BHHH is
+  the default to match GAUSS BHATLIB's `_max_CovPar=2`. All three are computed
+  at fit time and exposed as `se_bhhh` / `se_hessian` / `se_sandwich`;
+  `results.summary()` prints a side-by-side diagnostic block (a large
+  Hessian/BHHH divergence is a misspecification signal).
+- `MNPControl.active_mask` to freeze a subset of parameters at their starting
+  values without recoding the model.
+- `verbose` levels: `0` silent, `1` summary, `2` per-iteration NLL,
+  `3` per-iteration parameter / gradient / relative-gradient table.
+
+**Backend**
+- NumPy by default; optional PyTorch backend with GPU support (install with
+  `[torch]`). All numerical functions take an optional `xp` kwarg.
+
+**Post-estimation**
+- Average Treatment Effects (ATE) with scenario-matrix support, forecasting,
+  per-category MORP probability prediction.
+- MORP ATEs from supplied coefficients without re-fitting:
+  `MORPResults.from_estimates(beta, thresholds, correlation)` rebuilds a results
+  object from natural-space estimates, and `morp_ate_from_params` /
+  `morp_joint_probs` (mean joint category-combination probabilities, the GAUSS
+  `ate1.csv` equivalent) compute effects directly from them.
+
+## Verification
+
+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 |
+|-------|--------------|-----------|-------------|--------|
+| (a)(i)  | IID errors                  | -670.956 | -670.956 | exact match |
+| (a)(ii) | Flexible covariance         | -661.111 | -661.111 | exact match |
+| (b)     | + AGE45 demographics        | -659.285 | -659.284 | exact match |
+| (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 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
+at 1 and only correlations are estimated. The full-covariance `MORP_DINING` /
+`MORP_WALK` models reproduce the GAUSS mean log-likelihoods (−4.6598 / −3.7591)
+and correlation matrices. `summary()` reports the actual threshold cut-points
+(with delta-method standard errors) and a gradient column, matching GAUSS's
+output. See `docs/plans/MORP_BHATLIB_PARITY.md`.
+
+The driving notebooks are
+[`t04h_bhatlib_table1.ipynb`](https://github.com/UMN-Choi-Lab/pybhatlib/blob/main/examples/tutorials/t04h_bhatlib_table1.ipynb) and
+[`t04i_bhat2018_table2.ipynb`](https://github.com/UMN-Choi-Lab/pybhatlib/blob/main/examples/tutorials/t04i_bhat2018_table2.ipynb).
+
+## Tutorials
+
+A complete tutorial series lives under
+[`examples/tutorials/`](https://github.com/UMN-Choi-Lab/pybhatlib/tree/main/examples/tutorials/) as Jupyter notebooks (each with a
+matching `.py` script under `python_scripts/`):
+
+| Track | Notebooks |
+|-------|-----------|
+| Foundations | `t00_quickstart`, `t01a_vectorization`, `t01b_ldlt`, `t01c_truncated_mvn` |
+| Matrix gradients | `t02a_gradcovcor`, `t02b_spherical`, `t02c_chain_rules` |
+| MVNCD | `t03a_mvncd_methods`, `t03b_mvncd_gradients`, `t03c_mvncd_rect`, `t03d_univariate_cdfs`, `t03e_bhat2018_table1` |
+| 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
+
+See [`CONTRIBUTING.md`](https://github.com/UMN-Choi-Lab/pybhatlib/blob/main/CONTRIBUTING.md) for development setup, the PR-test
+workflow, and CODEOWNERS conventions. Key tests:
+
+```bash
+pytest tests/                 # full suite
+pytest tests/ -m "not slow"   # skip integration tests
+pytest tests/ -m torch        # PyTorch backend tests only
+```
+
+## References
+
+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. (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
+
+MIT