logit-stream 0.1.0__tar.gz

logit_stream-0.1.0/CHANGELOG.md

@@ -0,0 +1,86 @@
+# Changelog
+
+## 0.1.0
+
+The first release: logit models by streamed Newton's method, for data that
+do not fit in memory. Formulas are pyfixest-style (hdfe-stream's front end);
+data are Parquet files, Polars LazyFrames or DataFrames. Pass 0 writes the
+evaluated design as blocks of arrays, and each Newton step is one read of
+them.
+
+### Models
+
+- **Binary:** `logit_stream` and `probit_stream` (hdfe-stream's `feglm_stream`),
+  with any number of absorbed fixed effects, fit statistics (`loglik`,
+  `aic`, `bic`, `pseudo_r2_within`) and the incidental-parameter bias
+  correction (`bias_correction=`).
+- **Multinomial and ordered:** `mlogit_stream`, `ologit_stream` and
+  `oprobit_stream`.
+- **Conditional (McFadden):** `clogit_stream`; the conditional logit drops a
+  choice set whole when an alternative has missing values (Stata's
+  `cmclogit`), or keeps the complete alternatives with `altwise=True`.
+- **Panels:** `cfelogit_stream`, Chamberlain's conditional fixed-effects logit
+  (Stata's `xtlogit, fe`); matches statsmodels' `ConditionalLogit`.
+- **Nested logit** (experimental): `nlogit_stream`, a tree of nests of any
+  depth, in the utility-consistent normalization (Stata's `nlogit`
+  default). Matches R's mlogit.
+- **Mixed logit** (experimental prototype): `mixlogit_stream`, by streamed
+  maximum simulated likelihood, with normal and lognormal coefficients,
+  panels, and Halton or pseudo-random draws regenerated in every read.
+- **Firth's penalized likelihood** (`firth=True`) for the multinomial and
+  binary logit, matching brglm2 and logistf; an optional ridge penalty
+  (`l2=`).
+
+### Fixed and random effects
+
+- One absorbed fixed effect for the multinomial and ordered logit, solved
+  exactly in each Newton step (`"y ~ x | puma"`); several for the
+  multinomial logit (`"y ~ x | a + b"`), fitted as the equivalent Poisson
+  regression on the data expanded by outcome level (`fepois_stream`).
+- Random intercepts for the multinomial and ordered logit (`random=`;
+  experimental): Laplace's approximation (matching `glmer` and ordinal's
+  `clmm`) or the joint mode, with an unstructured or diagonal covariance
+  over the outcome levels. Nested groupings at any depth, optionally within
+  a fixed effect, or two crossed. `varcorr()` and `ranef()` report the
+  covariance and the predicted effects.
+- With a fixed effect, `loglik_fe_null` and `pseudo_r2_within`.
+
+### Inference and results
+
+- Variances: iid, heteroskedasticity-robust and clustered (one-way,
+  multi-way, or by an interaction), with Stata's small-sample factors for
+  maximum likelihood; the cluster jackknife (`{"CRV3": var}`). Frequency
+  weights, and analytic weights rescaled to average 1 as Stata does.
+- Results subclass hdfe-stream's `RegressionResult`: `summary`, `tidy`,
+  `confint` (pointwise or simultaneous), `wald_test`, `with_vcov`,
+  `to_pyfixest` and `etable`, and lazy `predict`, `resid` (including the
+  ordered models' probability-scale and generalized residuals), `sample` and
+  `fixef`.
+- `offset=` and warm starts (`start=`).
+- Convergence by the Newton decrement, with step-halving and a
+  Levenberg–Marquardt fallback, collinearity detection and warnings for
+  separated coefficients.
+
+### Scale and speed
+
+- **GPU** (`device="cuda"`, experimental): the Newton passes and the
+  variances' scores pass of every model, on an NVIDIA GPU through CuPy, with
+  the blocks kept on the device when they fit; `polars_engine="gpu"` runs
+  pass 0 on Polars' GPU engine. Tested on a numpy stand-in; the GPU
+  benchmark covers the hardware.
+- 0/1 design columns are stored as one byte each, and the multinomial
+  information is computed from each row's nonzeros when the design is mostly
+  indicators.
+- Numba kernels that accumulate per thread (the nested, mixed and
+  conditional fixed-effects logit).
+- `storage=`, `dtype=`, `block_mb=` and `chunk_mb=` control the block store.
+
+### Tools
+
+- `logit_stream.simulate`: `simulate_people`, `simulate_choices` (with
+  nests, or tasks and a random coefficient) and `simulate_panel`.
+- `examples/`: a standalone script for each page of the guide.
+- `benchmarks/`: ACS microdata, the Swissmetro survey, simulated panels and a
+  GPU suite, against scikit-learn, statsmodels, mord, pyfixest, xlogit,
+  jaxlogit, Biogeme, and R's glm, fixest, nnet, MASS, ordinal, survival,
+  mlogit, logitr and alpaca. Resumable.

logit_stream-0.1.0/CITATION.cff

@@ -0,0 +1,21 @@
+cff-version: 1.2.0
+message: "If you use this software in your research, please cite it as below."
+type: software
+title: "logit-stream"
+abstract: "Out-of-core logit models: binary, multinomial, ordered, conditional, nested, mixed and panel logit, with fixed and random effects, for data that do not fit in memory."
+authors:
+  - family-names: Tucker
+    given-names: Lee
+    email: lee.c.tucker@census.gov
+version: 0.1.0
+date-released: 2026-10-29
+license: MIT
+repository-code: "https://github.com/leetucker/logit-stream"
+url: "https://github.com/leetucker/logit-stream"
+keywords:
+  - econometrics
+  - logit
+  - multinomial logit
+  - discrete choice
+  - out-of-core
+  - fixed effects

logit_stream-0.1.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lee Tucker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

logit_stream-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include LICENSE.md README.md CHANGELOG.md CITATION.cff
+include logit_stream/py.typed

logit_stream-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: logit-stream
+Version: 0.1.0
+Summary: Out-of-core logit models by streamed Newton: binary, multinomial, ordered and conditional logit, with absorbed fixed effects
+Author: Lee Tucker
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/leetucker/logit-stream
+Project-URL: Source, https://github.com/leetucker/logit-stream
+Project-URL: Issues, https://github.com/leetucker/logit-stream/issues
+Project-URL: Documentation, https://leetucker.github.io/logit-stream/
+Project-URL: Changelog, https://github.com/leetucker/logit-stream/blob/main/CHANGELOG.md
+Keywords: econometrics,logit,multinomial logit,ordered logit,conditional logit,discrete choice,out-of-core,fixed effects,imputation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: hdfe-stream[formula]<0.7,>=0.6
+Requires-Dist: polars!=1.41.*,>=1.37
+Requires-Dist: numpy>=1.24
+Requires-Dist: numba>=0.59
+Requires-Dist: pyarrow>=14.0
+Requires-Dist: scipy>=1.11
+Requires-Dist: threadpoolctl>=3.1
+Provides-Extra: benchmark
+Requires-Dist: scikit-learn>=1.5; extra == "benchmark"
+Requires-Dist: statsmodels>=0.14; extra == "benchmark"
+Requires-Dist: xlogit>=0.2.7; extra == "benchmark"
+Requires-Dist: pylogit>=1.0.1; extra == "benchmark"
+Requires-Dist: mord>=0.7; extra == "benchmark"
+Requires-Dist: matplotlib>=3.7; extra == "benchmark"
+Requires-Dist: pandas>=2.0; extra == "benchmark"
+Provides-Extra: docs
+Requires-Dist: sphinx>=8.0; extra == "docs"
+Requires-Dist: myst-parser>=4.0; extra == "docs"
+Requires-Dist: furo>=2024.8.6; extra == "docs"
+Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
+Requires-Dist: sphinx-design>=0.6; extra == "docs"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: scikit-learn>=1.5; extra == "test"
+Requires-Dist: statsmodels>=0.14; extra == "test"
+Requires-Dist: pandas>=2.0; extra == "test"
+Dynamic: license-file
+
+# logit-stream
+
+Logit models for data that do not fit in memory: binary, multinomial,
+ordered, conditional, nested and mixed logit, fitted by Newton's method with
+the data streamed off disk, from
+[pyfixest](https://github.com/py-econometrics/pyfixest)-style formulas, with
+absorbed fixed effects or random intercepts.
+
+```python
+from logit_stream import mlogit_stream
+
+fit = mlogit_stream(
+    "race ~ C(agecat) + female + C(inccat) + C(cit) | puma",
+    "acs/*.parquet",               # a Parquet path or glob, never fully loaded
+    vcov={"CRV1": "puma"},
+)
+fit.summary()
+fit.predict("people/*.parquet").sink_parquet("imputed.parquet")   # lazily
+```
+
+| | |
+|---|---|
+| `logit_stream`, `probit_stream` | binary logit and probit with any number of fixed effects ([hdfe-stream](https://github.com/leetucker/hdfe-stream)'s `feglm_stream`) |
+| `mlogit_stream` | multinomial logit (any number of fixed effects; several through a Poisson regression) |
+| `ologit_stream`, `oprobit_stream` | ordered logit and probit |
+| `clogit_stream` | conditional (McFadden) logit on long-format choice data |
+| `cfelogit_stream` | Chamberlain's conditional fixed-effects logit for panels |
+| `mixlogit_stream`, `nlogit_stream` | mixed and nested logit (prototypes) |
+
+Newton's method for a logit needs the data only through sums over rows -- the
+log-likelihood, its gradient and the information matrix -- so each step is one
+read of the data, block by block, and one dense solve; the likelihoods are
+concave, so a handful of steps suffice. Memory grows with the number of
+coefficients, not of rows. The multinomial and ordered logit absorb one fixed
+effect exactly, by eliminating its per-level blocks of the information matrix
+in every step.
+
+Results share [hdfe-stream](https://github.com/leetucker/hdfe-stream)'s
+reporting: `summary()`, `tidy()`, `summary_dict()`, `summary_json()`,
+`confint()`, `wald_test()`, `with_vcov()`, `etable()`, and lazy `predict()`,
+`resid()`, `sample()` and `fixef()` frames. Estimates and standard errors
+match statsmodels and scikit-learn (see `tests/`).
+
+Documentation: <https://leetucker.github.io/logit-stream/> (build locally with
+`pip install -e ".[docs]"` and `sphinx-build -b html docs docs/_build/html`).
+`examples/` has a runnable script for each page of its guide, on simulated
+data.
+
+## Install
+
+```bash
+pip install logit-stream
+```
+
+Python 3.10 or later. On Python 3.15, pyfixest 0.60 (which hdfe-stream's
+formula extra brings in) has no wheels yet: it builds from source with a Rust
+toolchain and `PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1` set; everything else
+installs from wheels.
+
+## Benchmarks
+
+`benchmarks/` compares logit-stream with scikit-learn, statsmodels, mord and
+R's glm, fixest, nnet, MASS and ordinal on American Community Survey
+microdata (10,000 to 12.9 million adults); with xlogit, pylogit,
+statsmodels, jaxlogit, Biogeme and R's mlogit and logitr on the Swissmetro
+choice survey, resampled to 10 million choice sets; on short panels with
+statsmodels and R's survival, fixest and alpaca; and on a GPU. See
+`benchmarks/README.md` and the documentation's benchmark pages.
+
+## License
+
+MIT.

logit_stream-0.1.0/README.md

@@ -0,0 +1,72 @@
+# logit-stream
+
+Logit models for data that do not fit in memory: binary, multinomial,
+ordered, conditional, nested and mixed logit, fitted by Newton's method with
+the data streamed off disk, from
+[pyfixest](https://github.com/py-econometrics/pyfixest)-style formulas, with
+absorbed fixed effects or random intercepts.
+
+```python
+from logit_stream import mlogit_stream
+
+fit = mlogit_stream(
+    "race ~ C(agecat) + female + C(inccat) + C(cit) | puma",
+    "acs/*.parquet",               # a Parquet path or glob, never fully loaded
+    vcov={"CRV1": "puma"},
+)
+fit.summary()
+fit.predict("people/*.parquet").sink_parquet("imputed.parquet")   # lazily
+```
+
+| | |
+|---|---|
+| `logit_stream`, `probit_stream` | binary logit and probit with any number of fixed effects ([hdfe-stream](https://github.com/leetucker/hdfe-stream)'s `feglm_stream`) |
+| `mlogit_stream` | multinomial logit (any number of fixed effects; several through a Poisson regression) |
+| `ologit_stream`, `oprobit_stream` | ordered logit and probit |
+| `clogit_stream` | conditional (McFadden) logit on long-format choice data |
+| `cfelogit_stream` | Chamberlain's conditional fixed-effects logit for panels |
+| `mixlogit_stream`, `nlogit_stream` | mixed and nested logit (prototypes) |
+
+Newton's method for a logit needs the data only through sums over rows -- the
+log-likelihood, its gradient and the information matrix -- so each step is one
+read of the data, block by block, and one dense solve; the likelihoods are
+concave, so a handful of steps suffice. Memory grows with the number of
+coefficients, not of rows. The multinomial and ordered logit absorb one fixed
+effect exactly, by eliminating its per-level blocks of the information matrix
+in every step.
+
+Results share [hdfe-stream](https://github.com/leetucker/hdfe-stream)'s
+reporting: `summary()`, `tidy()`, `summary_dict()`, `summary_json()`,
+`confint()`, `wald_test()`, `with_vcov()`, `etable()`, and lazy `predict()`,
+`resid()`, `sample()` and `fixef()` frames. Estimates and standard errors
+match statsmodels and scikit-learn (see `tests/`).
+
+Documentation: <https://leetucker.github.io/logit-stream/> (build locally with
+`pip install -e ".[docs]"` and `sphinx-build -b html docs docs/_build/html`).
+`examples/` has a runnable script for each page of its guide, on simulated
+data.
+
+## Install
+
+```bash
+pip install logit-stream
+```
+
+Python 3.10 or later. On Python 3.15, pyfixest 0.60 (which hdfe-stream's
+formula extra brings in) has no wheels yet: it builds from source with a Rust
+toolchain and `PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1` set; everything else
+installs from wheels.
+
+## Benchmarks
+
+`benchmarks/` compares logit-stream with scikit-learn, statsmodels, mord and
+R's glm, fixest, nnet, MASS and ordinal on American Community Survey
+microdata (10,000 to 12.9 million adults); with xlogit, pylogit,
+statsmodels, jaxlogit, Biogeme and R's mlogit and logitr on the Swissmetro
+choice survey, resampled to 10 million choice sets; on short panels with
+statsmodels and R's survival, fixest and alpaca; and on a GPU. See
+`benchmarks/README.md` and the documentation's benchmark pages.
+
+## License
+
+MIT.

logit_stream-0.1.0/logit_stream/__init__.py

@@ -0,0 +1,77 @@
+"""logit-stream: logit models fitted out of core by streamed Newton.
+
+Binary (`logit_stream`, `probit_stream`: hdfe-stream's `feglm_stream`, with
+any number of absorbed fixed effects), multinomial (`mlogit_stream`),
+ordered (`ologit_stream`, `oprobit_stream`), conditional (`clogit_stream`),
+conditional fixed-effects (`cfelogit_stream`), mixed (`mixlogit_stream`) and
+nested (`nlogit_stream`) logit, from pyfixest-style formulas, on data that
+need not fit in memory: Parquet files, Polars LazyFrames, or DataFrames.
+
+Layout
+    api.py           the estimators
+    _frontend.py     formulas -> models (hdfe-stream's formula compiler)
+    store.py         pass 0, into hdfe-stream's block store (hdfe_stream.core.store)
+    models.py        the likelihoods: per chunk, log-likelihood, gradient,
+                     information, scores
+    newton.py        Newton's method, collinearity, the variance's middle matrix
+    estimator.py     formula + source -> result, and the inference
+    fe.py            one absorbed fixed effect (multinomial, ordered)
+    multi_fe.py      several, for the multinomial logit (a Poisson regression)
+    random_effects/  random intercepts (Laplace's approximation)
+    optimize.py      Newton and quasi-Newton steps from an analytic gradient,
+                     for the likelihoods that are not concave
+    _choice.py       what the mixed and nested logit's fits share
+    mixed.py         the mixed logit (simulated likelihood)
+    nested.py        the nested logit
+    device/          the passes on a GPU (CuPy)
+    results.py       the result classes
+    simulate.py      simulated data for examples and tests
+"""
+
+from __future__ import annotations
+
+from hdfe_stream.core.multcomp import bonferroni, holm
+from hdfe_stream.core.reporting import etable
+
+from .api import (
+    cfelogit_stream,
+    clogit_stream,
+    logit_stream,
+    mixlogit_stream,
+    mlogit_stream,
+    nlogit_stream,
+    ologit_stream,
+    oprobit_stream,
+    probit_stream,
+)
+from .results import (
+    ConditionalFELogitResult,
+    ConditionalLogitResult,
+    LogitMulti,
+    LogitResult,
+    MixedLogitResult,
+    MultinomialLogitResult,
+    NestedLogitResult,
+    OrderedLogitResult,
+    OrderedProbitResult,
+)
+
+
+def _version():
+    try:
+        from importlib.metadata import version
+        return version("logit-stream")
+    except Exception:                   # noqa: BLE001 -- not installed
+        return "0.1.0"
+
+
+__version__ = _version()
+
+__all__ = [
+    "logit_stream", "probit_stream", "mlogit_stream", "ologit_stream", "oprobit_stream",
+    "clogit_stream", "cfelogit_stream", "mixlogit_stream", "nlogit_stream",
+    "LogitResult", "MultinomialLogitResult", "OrderedLogitResult", "OrderedProbitResult",
+    "ConditionalLogitResult", "ConditionalFELogitResult",
+    "MixedLogitResult", "NestedLogitResult",
+    "LogitMulti", "etable", "bonferroni", "holm", "__version__",
+]

logit_stream-0.1.0/logit_stream/_choice.py

@@ -0,0 +1,64 @@
+"""What the fits on choice data with `optimize._GradientDriver` (the mixed
+and the nested logit) share: the one formula, the conditional logit as the
+starting point, and the diagnostics of the fit."""
+
+from __future__ import annotations
+
+import time
+
+import numpy as np
+
+
+def plan_one(fml, lf, engine, log, model):
+    """The formula's one model, without fixed effects (`model` names the
+    estimator in the errors)."""
+    from ._frontend import _plan
+    log(f"planning {fml!r}")
+    specs = _plan(fml, lf, intercept=False, collect=lambda q, what: engine.collect(q, what))
+    if len(specs) != 1:
+        raise ValueError(f"multiple estimation is not available for the {model}")
+    spec = specs[0]
+    if spec.fe:
+        raise ValueError(f"{spec.fml}: fixed effects are not available for the {model}")
+    return spec
+
+
+def clogit_start(p0, xnames, spec, logger, log):
+    """The conditional logit on the store: the starting point (it refuses
+    collinear covariates, which these fits do not drop)."""
+    from .models import _Conditional
+    from .newton import _Driver
+    log("starting values: the conditional logit")
+    K = len(xnames)
+    cdrv = _Driver(p0.store, _Conditional(xnames, K), tol=1e-8, maxiter=50, l2=0.0,
+                   chunk_mb=64.0, log=lambda m: None, logger=logger)
+    cfit = cdrv.run(np.zeros(K), spec.fml)
+    if cfit.dropped:
+        raise ValueError(f"{spec.fml}: collinear covariates {cfit.dropped}; drop them (they "
+                         "are not dropped for this model)")
+    return cfit
+
+
+def fit_diagnostics(fit, cfit, p0, *, storage, dtype, tol, t0, device=None, drv=None,
+                    **more):
+    """The diagnostics of a `_GradientFit` started from `cfit`."""
+    out = {
+        "optimizer": {"iterations": fit.iterations, "bhhh_steps": fit.bhhh_steps,
+                      "newton_steps": fit.newton_steps, "quasi_steps": fit.quasi_steps,
+                      "converged": fit.converged, "decrement": fit.decrement,
+                      "loglik": fit.path, "passes": fit.passes, "seconds": fit.seconds,
+                      "tol": tol},
+        "start": {"loglik_clogit": float(cfit.ll), "passes": cfit.passes},
+        "gradient": [float(v) for v in fit.g],
+        "pass0_seconds": p0.seconds, "n_rows": p0.n_obs, "n_raw": p0.n_raw,
+        "store": {"storage": storage, "dtype": dtype, "blocks": len(p0.store.blocks),
+                  "bytes": int(p0.store.bytes)},
+        "disk_peak_gb": round((p0.store.bytes if storage == "disk" else 0) / 1e9, 4),
+        "seconds_total": round(time.time() - t0, 2),
+        **more,
+    }
+    if device is not None:
+        ds = drv._dstore
+        out["device"] = {"name": device.name, "resident": bool(ds and ds.resident),
+                         "bytes": int(ds.bytes) if ds else 0}
+    return out

logit_stream-0.1.0/logit_stream/_frontend.py

@@ -0,0 +1,78 @@
+"""Formula front end: a pyfixest-style formula -> the models to fit.
+
+The right-hand side is compiled by hdfe-stream's formula compiler
+(`hdfe_stream.core.formula`), which runs pyfixest's own parser and model
+matrix on a tiny synthetic frame and turns each column back into a Polars
+expression. Coefficient names and the coding of categorical variables are
+therefore exactly pyfixest's. The outcome is handled here: for the
+multinomial and ordered models it is a categorical variable, not a number,
+so it is kept as a raw column and coded once its levels are known.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import polars as pl
+from hdfe_stream.core.feterms import parse_fe
+from hdfe_stream.core.formula import (
+    categorical_vars,
+    compile_design,
+    numeric_expr,
+    pyfixest_formula_api,
+)
+
+
+@dataclass
+class _Spec:
+    """One model: its formula, outcome, covariates and fixed effects."""
+
+    fml: str
+    depvar: str
+    y: pl.Expr                      # the outcome, uncast
+    x: list = field(default_factory=list)       # [(coefficient name, Float64 expr)]
+    fe: tuple = ()
+
+
+def _outcome_expr(dep, schema):
+    """A column is taken as it is (strings, categoricals, integers);
+    anything else is a numeric expression such as ``I(educ > 12)``."""
+    if dep in schema:
+        return pl.col(dep)
+    return numeric_expr(dep)
+
+
+def _plan(fml: str, lf: pl.LazyFrame, intercept: bool, collect) -> list[_Spec]:
+    """Expand `fml` into its models (pyfixest's multiple-estimation syntax:
+    several outcomes, ``sw()``, ``csw()``, ...).
+
+    `intercept`: whether a model without fixed effects gets the model
+    matrix's constant (multinomial logit does; ordered and conditional logit
+    do not, their cutpoints and choice sets absorbing it). Without it the
+    categorical coding is still reduced rank, as with it.
+    `collect(lf, what)` runs a query (so that the GPU engine applies).
+    """
+    Formula, _ = pyfixest_formula_api()
+    schema = lf.collect_schema()
+    specs = Formula.parse(fml)
+    cats = set()
+    for s in specs:
+        if s.first_stage is not None:
+            raise ValueError(f"{s.formula}: IV formulas are not available for logit models")
+        cats |= categorical_vars(s.second_stage.split("~", 1)[1], schema)
+    levels = {}
+    for v in sorted(cats):
+        u = collect(lf.select(pl.col(v).drop_nulls().unique().sort()), f"levels of {v}")
+        levels[v] = u[v].to_list()
+    out = []
+    for s in specs:
+        dep, rhs = (t.strip() for t in s.second_stage.split("~", 1))
+        fe = tuple(parse_fe(s.fixed_effects))
+        for d in fe:
+            if "[" in d:
+                raise ValueError(f"{s.formula}: varying slopes are not available for logit models")
+        _, cols = compile_design(dep, rhs, schema, levels, intercept=intercept and not fe)
+        if not intercept:
+            cols = [(nm, ex) for nm, ex in cols if nm != "Intercept"]
+        out.append(_Spec(fml=s.formula, depvar=dep, y=_outcome_expr(dep, schema), x=cols, fe=fe))
+    return out