mnlite 0.1.0__py3-none-any.whl

mnlite/__init__.py

@@ -0,0 +1,46 @@
+"""mnlite: lightweight multinomial and nested logit models for travel mode choice.
+
+Estimation by maximum likelihood with analytic gradients (numpy only), robust
+standard errors, goodness-of-fit statistics, likelihood ratio tests,
+elasticities, value of travel time with delta-method standard errors and
+market-share scenario simulation.
+"""
+
+from __future__ import annotations
+
+from ._version import __version__
+from .data import ChoiceData, DataError, read_csv
+from .datasets import ben_akiva_lerman, synthetic_mode_choice, synthetic_spec
+from .estimation import (
+    EstimationResults,
+    LRTest,
+    RatioEstimate,
+    ScenarioResult,
+    compare,
+    estimate,
+    lr_test,
+)
+from .models import ChoiceModel
+from .spec import Spec, SpecError, Term, parse_utility
+
+__all__ = [
+    "__version__",
+    "ChoiceData",
+    "ChoiceModel",
+    "DataError",
+    "EstimationResults",
+    "LRTest",
+    "RatioEstimate",
+    "ScenarioResult",
+    "Spec",
+    "SpecError",
+    "Term",
+    "ben_akiva_lerman",
+    "compare",
+    "estimate",
+    "lr_test",
+    "parse_utility",
+    "read_csv",
+    "synthetic_mode_choice",
+    "synthetic_spec",
+]

mnlite/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m mnlite``."""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())

mnlite/_stats.py

@@ -0,0 +1,86 @@
+"""Small distribution helpers so that mnlite does not need scipy.
+
+The chi-square survival function uses the regularised upper incomplete gamma
+function evaluated with the series / continued-fraction pair described in
+Press, Teukolsky, Vetterling & Flannery (2007), *Numerical Recipes*, 3rd ed.,
+section 6.2.
+"""
+
+from __future__ import annotations
+
+import math
+
+__all__ = ["norm_sf", "norm_ppf", "chi2_sf"]
+
+
+def norm_sf(z: float) -> float:
+    """Upper tail probability ``P(Z > z)`` of the standard normal distribution."""
+    return 0.5 * math.erfc(z / math.sqrt(2.0))
+
+
+def norm_ppf(p: float) -> float:
+    """Quantile of the standard normal distribution (bisection on ``erfc``).
+
+    Accurate to about 1e-12, which is ample for confidence intervals.
+    """
+    if not 0.0 < p < 1.0:
+        raise ValueError("p must lie strictly between 0 and 1")
+    lo, hi = -40.0, 40.0
+    for _ in range(200):
+        mid = 0.5 * (lo + hi)
+        if 1.0 - norm_sf(mid) < p:
+            lo = mid
+        else:
+            hi = mid
+        if hi - lo < 1e-14:
+            break
+    return 0.5 * (lo + hi)
+
+
+def _gamma_p_series(a: float, x: float) -> float:
+    term = 1.0 / a
+    total = term
+    ap = a
+    for _ in range(10_000):
+        ap += 1.0
+        term *= x / ap
+        total += term
+        if abs(term) < abs(total) * 1e-16:
+            break
+    return total * math.exp(-x + a * math.log(x) - math.lgamma(a))
+
+
+def _gamma_q_cf(a: float, x: float) -> float:
+    tiny = 1e-300
+    b = x + 1.0 - a
+    c = 1.0 / tiny
+    d = 1.0 / b
+    h = d
+    for i in range(1, 10_000):
+        an = -i * (i - a)
+        b += 2.0
+        d = an * d + b
+        if abs(d) < tiny:
+            d = tiny
+        c = b + an / c
+        if abs(c) < tiny:
+            c = tiny
+        d = 1.0 / d
+        delta = d * c
+        h *= delta
+        if abs(delta - 1.0) < 1e-16:
+            break
+    return math.exp(-x + a * math.log(x) - math.lgamma(a)) * h
+
+
+def chi2_sf(x: float, df: float) -> float:
+    """Survival function ``P(X > x)`` of a chi-square variable with ``df`` degrees of freedom."""
+    if df <= 0:
+        raise ValueError("df must be positive")
+    if x <= 0:
+        return 1.0
+    a = 0.5 * df
+    half = 0.5 * x
+    if half < a + 1.0:
+        return max(0.0, 1.0 - _gamma_p_series(a, half))
+    return min(1.0, _gamma_q_cf(a, half))

mnlite/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

mnlite/cli.py

@@ -0,0 +1,246 @@
+"""Command line interface: ``mnlite estimate | synth | convert | example``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any, Dict, List, Optional, Sequence
+
+from ._version import __version__
+from .data import ChoiceData, read_table
+from .datasets import BEN_AKIVA_LERMAN_SPEC, ben_akiva_lerman, synthetic_mode_choice
+from .estimation import EstimationResults, estimate
+from .spec import Spec
+
+__all__ = ["main"]
+
+
+def _kv(items: Optional[Sequence[str]], sep: str, what: str) -> Dict[str, str]:
+    out: Dict[str, str] = {}
+    for it in items or []:
+        if sep not in it:
+            raise SystemExit(f"error: {what} {it!r} must look like NAME{sep}VALUE")
+        k, v = it.split(sep, 1)
+        out[k.strip()] = v.strip()
+    return out
+
+
+def _load_data(args: argparse.Namespace, alts: Optional[List[str]]) -> ChoiceData:
+    table = read_table(args.data)
+    if args.long:
+        return ChoiceData.from_long(
+            table,
+            id_col=args.id_col,
+            alt_col=args.alt_col,
+            choice_col=args.choice,
+            alternatives=alts,
+            avail_col=args.avail,
+            weights=args.weights,
+        )
+    return ChoiceData.from_wide(
+        table, alternatives=alts, choice=args.choice, avail=args.avail, weights=args.weights
+    )
+
+
+def _add_data_args(p: argparse.ArgumentParser, choice_default: str = "choice") -> None:
+    p.add_argument("data", help="input CSV file")
+    p.add_argument("--long", action="store_true", help="input is in long form")
+    p.add_argument(
+        "--choice",
+        default=None,
+        help=f"choice column (wide: chosen alternative, default {choice_default!r}; "
+        "long: 0/1 indicator, default 'chosen')",
+    )
+    p.add_argument("--id-col", default="id", help="long form: observation id column")
+    p.add_argument("--alt-col", default="alt", help="long form: alternative column")
+    p.add_argument(
+        "--avail",
+        default=None,
+        help="wide: availability column pattern such as '{alt}_av'; long: 0/1 column",
+    )
+    p.add_argument("--weights", default=None, help="observation weight column")
+    p.add_argument("--alts", default=None, help="comma-separated alternatives (sets the order)")
+
+
+def _fix_choice_default(args: argparse.Namespace) -> None:
+    if args.choice is None:
+        args.choice = "chosen" if args.long else "choice"
+
+
+def _build_spec(args: argparse.Namespace) -> Spec:
+    if args.spec:
+        with open(args.spec, encoding="utf-8") as fh:
+            d = json.load(fh)
+        return Spec.from_dict(d)
+    utils = _kv(args.utility, "=", "--utility")
+    if not utils:
+        raise SystemExit("error: give --spec FILE.json or at least one --utility ALT=EXPR")
+    nests = {k: [m.strip() for m in v.split(",")] for k, v in _kv(args.nest, ":", "--nest").items()}
+    fixed = {k: float(v) for k, v in _kv(args.fix, "=", "--fix").items()}
+    alts = args.alts.split(",") if args.alts else None
+    if alts:
+        for a in alts:
+            utils.setdefault(a.strip(), "0")
+    return Spec(utils, nests=nests or None, fixed=fixed, alternatives=alts)
+
+
+def _report(res: EstimationResults, data: ChoiceData, args: argparse.Namespace) -> Dict[str, Any]:
+    extra: Dict[str, Any] = {}
+    for item in args.ratio or []:
+        scale = 1.0
+        expr = item
+        if "*" in expr:
+            expr, s = expr.split("*", 1)
+            scale = float(s)
+        num, den = (x.strip() for x in expr.split("/", 1))
+        r = res.ratio(num, den, scale, robust=args.robust)
+        print(r)
+        extra.setdefault("ratios", {})[r.name] = {"value": r.value, "se": r.se, "ci": list(r.ci)}
+    for item in args.elasticity or []:
+        if ":" in item:
+            var, alt = item.split(":", 1)
+            e = res.elasticities(data, var.strip(), alt.strip())
+        else:
+            e = res.elasticities(data, item.strip())
+        assert isinstance(e, dict)
+        print(f"Aggregate elasticities w.r.t. {item}:")
+        for a, v in e.items():
+            print(f"  P({a}): {v:+.4f}")
+        extra.setdefault("elasticities", {})[item] = e
+    if args.scenario:
+        changes: Dict[str, str] = {}
+        for sc in args.scenario:
+            for op in ("*", "+", "=", "/", "-"):
+                if op in sc:
+                    col, val = sc.split(op, 1)
+                    changes[col.strip()] = op + val.strip()
+                    break
+            else:
+                raise SystemExit(
+                    f"error: cannot parse scenario {sc!r}; use COL*1.1, COL+5, COL-5, COL=0"
+                )
+        sim = res.simulate(data, changes)
+        print("Scenario: " + ", ".join(f"{k}{v}" for k, v in changes.items()))
+        print(sim.table())
+        extra["scenario"] = {"changes": changes, "base": sim.base, "scenario": sim.scenario}
+    return extra
+
+
+def _cmd_estimate(args: argparse.Namespace) -> int:
+    _fix_choice_default(args)
+    spec = _build_spec(args)
+    data = _load_data(args, spec.alts)
+    res = estimate(spec, data, method=args.method, constants_ll=not args.no_constants)
+    print(res.summary(robust=True))
+    extra = _report(res, data, args)
+    if args.json:
+        d = res.to_dict()
+        d.update(extra)
+        with open(args.json, "w", encoding="utf-8") as fh:
+            json.dump(d, fh, indent=2)
+        print(f"results written to {args.json}")
+    return 0 if res.converged else 1
+
+
+def _cmd_synth(args: argparse.Namespace) -> int:
+    data = synthetic_mode_choice(args.n, args.seed, nested=args.nested)
+    data.write_csv(args.out, "long" if args.long else "wide")
+    print(f"wrote {data.n} observations to {args.out}")
+    return 0
+
+
+def _cmd_convert(args: argparse.Namespace) -> int:
+    _fix_choice_default(args)
+    alts = args.alts.split(",") if args.alts else None
+    data = _load_data(args, alts)
+    data.write_csv(args.out, args.to)
+    print(f"wrote {data.n} observations ({args.to} form) to {args.out}")
+    return 0
+
+
+def _cmd_example(args: argparse.Namespace) -> int:
+    data = ben_akiva_lerman()
+    res = estimate(BEN_AKIVA_LERMAN_SPEC, data)
+    print("Ben-Akiva & Lerman (1985, p. 88) car/transit example")
+    print(res.summary(robust=False))
+    print("Published: asc_transit 0.2376 (0.7505), b_time -0.0531 (0.0206), LL -6.166")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="mnlite",
+        description="Lightweight multinomial / nested logit estimation for mode choice.",
+    )
+    p.add_argument("--version", action="version", version=f"mnlite {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    e = sub.add_parser("estimate", help="estimate an MNL or nested logit model from a CSV")
+    _add_data_args(e)
+    e.add_argument("--spec", help="JSON spec file with 'utilities', 'nests', 'fixed'")
+    e.add_argument(
+        "-u",
+        "--utility",
+        action="append",
+        metavar="ALT=EXPR",
+        help="utility of one alternative, e.g. 'bus=asc_bus + b_time*time' (repeatable)",
+    )
+    e.add_argument("--nest", action="append", metavar="NEST:ALT1,ALT2", help="nest (repeatable)")
+    e.add_argument("--fix", action="append", metavar="PARAM=VALUE", help="fix a parameter")
+    e.add_argument("--method", default="auto", choices=["auto", "newton", "bfgs", "scipy"])
+    e.add_argument("--robust", action="store_true", help="use robust s.e. for ratios")
+    e.add_argument(
+        "--ratio",
+        action="append",
+        metavar="NUM/DEN[*SCALE]",
+        help="parameter ratio with delta-method s.e., e.g. VTT 'b_time/b_cost*60'",
+    )
+    e.add_argument(
+        "--elasticity",
+        action="append",
+        metavar="VAR:ALT|COLUMN",
+        help="aggregate elasticities w.r.t. a variable, e.g. 'cost:car' or 'cost_car'",
+    )
+    e.add_argument(
+        "--scenario",
+        action="append",
+        metavar="COL*X|COL+X|COL-X|COL=X",
+        help="scenario change of a column (repeatable; applied together)",
+    )
+    e.add_argument("--no-constants", action="store_true", help="skip the constants-only model")
+    e.add_argument("--json", help="write results to this JSON file")
+    e.set_defaults(func=_cmd_estimate)
+
+    s = sub.add_parser("synth", help="write the synthetic car/bus/rail dataset")
+    s.add_argument("out", help="output CSV")
+    s.add_argument("--n", type=int, default=2000)
+    s.add_argument("--seed", type=int, default=12345)
+    s.add_argument("--nested", action="store_true", help="simulate from the nested logit")
+    s.add_argument("--long", action="store_true", help="write long form")
+    s.set_defaults(func=_cmd_synth)
+
+    c = sub.add_parser("convert", help="convert between wide and long CSV")
+    _add_data_args(c)
+    c.add_argument("out", help="output CSV")
+    c.add_argument("--to", choices=["wide", "long"], required=True)
+    c.set_defaults(func=_cmd_convert)
+
+    x = sub.add_parser("example", help="run the Ben-Akiva & Lerman validation example")
+    x.set_defaults(func=_cmd_example)
+    return p
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        rc: int = args.func(args)
+    except (ValueError, KeyError, OSError) as exc:
+        print(f"mnlite: error: {exc}", file=sys.stderr)
+        return 2
+    return rc
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())