lme-python 0.2.3__tar.gz → 0.2.4__tar.gz

lme_python-0.2.4/AGENTS.md

@@ -0,0 +1,148 @@
+# Agent guide
+
+This is a Rust statistical library (`lme-rs`) with PyO3/maturin Python bindings
+(`lme_python`). There is no application server to start. Run commands from the
+repository root unless stated otherwise.
+
+## Start here
+
+1. Inspect `git status --short --branch` and the relevant diff. Preserve unrelated
+   changes; do not reset, stash, switch branches, or update dependencies as routine setup.
+2. Use `rg` and the map below to find the implementation and existing tests. Read
+   relevant guides rather than scanning the whole repository before a focused fix.
+3. Choose required checks before editing. Reproduce bugs with focused tests, fix
+   the cause, and verify both the regression and affected behavior.
+4. Update [CHANGELOG.md](CHANGELOG.md) under `Unreleased` for user-visible fixes,
+   features, and compatibility changes. Instruction-only edits need no entry.
+5. Review the final diff. Report changes, validation, and failures/skips/limitations;
+   do not claim unrun checks.
+
+## Code map
+
+| Area | Start with |
+|---|---|
+| Public API, contracts, reusable fits | `src/lib.rs`, `src/model.rs`, `src/prepared.rs` |
+| Formulas and design matrices | `src/formula.rs`, `src/model_matrix.rs`, `src/basis.rs` |
+| LMM / GLMM / nonlinear fitting | `src/math.rs`, `src/optimizer.rs`, `src/intercept_blocked.rs` / `src/glmm_math.rs`, `src/family.rs` / `src/nlmm/` |
+| Inference and post-fit behavior | `src/contrast.rs`, `src/ddf.rs`, `src/satterthwaite.rs`, `src/kenward_roger.rs`, `src/kr_modcomp.rs`; named modules such as `predict.rs`, `simulate.rs`, `emmeans.rs`, `mcp.rs`, `robust.rs` |
+| Python API and tests | `python/src/lib.rs`, `python/tests/` |
+| Regression tests and reference evidence | `tests/`, `tests/data/`, `comparisons/` |
+| Checks, aliases, hooks, tool versions | [scripts/ci/lme_ci.py](scripts/ci/lme_ci.py), [Taskfile.yml](Taskfile.yml), [lefthook.yml](lefthook.yml), [mise.toml](mise.toml) |
+
+## Required validation
+
+Use the smallest tier covering the change. Requirements from multiple rows combine;
+a successful broader check can satisfy its component checks.
+
+| Change | Minimum checks and escalation |
+|---|---|
+| Rust code | `task lint`, `task test:fast`, and affected integration tests; use `task rust` for cross-module or public-API changes |
+| Python bindings | `task lint:python`, `task python` |
+| CI, manifests, release tooling | `task preflight`; use `task ci` before a release or broad refactor |
+| R / Julia comparison scripts | `task lint:comparisons`; use `task lint:comparisons:required` when formatters are installed |
+| Documentation (including this file) or portable examples | `task docs:check`; add `task consumer:smoke` when install or example behavior changes |
+| LMM throughput paths (`src/math.rs`, `src/optimizer.rs`, related caches/solvers) | Read [OPTIMIZATION.md](OPTIMIZATION.md) and run applicable fair-harness cases in addition to Rust checks |
+| `README.md`, `REPO_COMPLETION_BY_AREA.md`, `completion_manifest.json`, `scripts/ci/check_completion_score.py` | `task completion:check` |
+
+### Avoid redundant work
+
+- Start with `cargo test --locked --test <test_target> <test_filter>` or
+  `cargo test --locked --lib <test_filter>`. Selecting zero tests proves nothing.
+- `task rust` includes Rust lint, all-target compilation, unit/integration tests,
+  doctests, and documentation generation. Add `task lint:python` for the Ruff part
+  of `task lint`; do not separately repeat `task test:fast`.
+- `task test` runs the full Rust suite. On Windows/macOS, `task test:consolidated`
+  runs unit and integration tests with one integration executable, checks examples,
+  and runs doctests. It can replace `task test` when linking is costly. An equivalent
+  Rust validation slice is `task lint:rust`, `task check`, `task test:consolidated`,
+  and `python scripts/ci/lme_ci.py doc`.
+- `task ci` includes Rust, bindings, portable examples, lint, compilation, legal,
+  documentation, and completion checks. It does not replace audits/metadata in
+  `task preflight`, R/Julia checks, or performance harnesses. `task ci:fast` skips
+  the isolated-wheel pass; report that limitation.
+- Reuse passing results for unchanged files/dependencies in the same task. Rerun
+  affected checks after edits; broaden when scope or evidence requires it.
+  Keep hooks enabled even when they repeat earlier checks.
+- Serialize Cargo commands sharing a target directory. Capture verbose logs and
+  inspect exit status and summaries. A timeout or compilation in progress is not a failed test.
+
+## Correctness and evidence
+
+- Add regression coverage for bug fixes. Prefer statistical identities, explicit
+  expected behavior, and independent fixtures over duplicating the implementation.
+- Register new integration test files in [tests/ci_consolidated.rs](tests/ci_consolidated.rs).
+- For R/Julia parity, match rows, formula, family/link, weights, offsets, and ML/REML.
+  Explain tolerances; do not loosen them just to make a failure pass.
+- Tie benchmark claims to the revision, environment, and measured cases. Follow
+  [BENCHMARKS.md](BENCHMARKS.md) and [OPTIMIZATION.md](OPTIMIZATION.md); a focused
+  speedup does not establish general parity or completion.
+
+### Completion scores are generated claims
+
+[completion_manifest.json](completion_manifest.json) governs the README headline
+and all percentages in [REPO_COMPLETION_BY_AREA.md](REPO_COMPLETION_BY_AREA.md).
+It declares weighted binary commitments, locked `scope` strings, evidence paths,
+and a `gap` for every incomplete criterion.
+
+- Complete an item only when its locked scope is met and evidence is current.
+  Partial, stale, or substituted evidence earns zero; an API or focused benchmark is insufficient.
+- Do not narrow/replace `scope` to earn credit or edit generated percentages by hand.
+  Update the manifest and supporting evidence together.
+- `task completion:check` validates schema version 2, names/scopes/gaps, evidence
+  paths, arithmetic, report rows, and the README headline. `task ci` includes it.
+
+## Setup and recovery
+
+- [mise.toml](mise.toml) configures Rust stable, Python 3.11, uv, Task, and Lefthook.
+  Use `task setup` for tools and hooks; run `mise install` first if Task is missing.
+  With tools already installed, use `task hooks:install`. Pre-push audits also
+  require `cargo-audit` (`cargo install cargo-audit`).
+- For missing PATH entries, use `mise exec -- task <name>`. Locate installed tools
+  before reinstalling. Verify subprocess discovery in the actual environment with
+  `python -c "import shutil; print(shutil.which('uv'))"` when necessary.
+- Without Task, use `python scripts/ci/lme_ci.py <subcommand>` (`python3` where
+  appropriate). Mappings are in [Taskfile.yml](Taskfile.yml): `test:fast` → `test-fast`,
+  `rust` → `rust-all`, `lint:python` → `ruff-lint`, `docs:check` → `docs-check`.
+  Use `--help` for all commands. Implement new checks in this runner, not duplicate shell logic.
+- For Git dubious ownership, use `git -c safe.directory=C:/path/to/lme-rs <command>`
+  with this checkout's absolute forward-slash path; do not trust all directories globally.
+- x86_64 builds link static Intel MKL via `ndarray-linalg`; first builds can be slow.
+  Run numerical examples with `--release`, e.g. `cargo run --release --locked --example sleepstudy`.
+  Leave the CI runner's own build profiles unchanged.
+- Windows linker errors `LNK1318`/`LNK1106` can indicate disk exhaustion. Check space
+  and active builds first. Before cleaning, verify the target belongs to this checkout
+  and no build uses it; avoid broad cache deletion.
+- `uv sync` can uninstall the editable Python extension. Restore it from `python/`
+  with `uv run --no-sync maturin develop --release`, or rerun `task python`.
+  Run Python examples there with `uv run --no-sync python examples/<name>.py`.
+
+## Git, hooks, and release boundaries
+
+- Follow the user's commit/push scope; commit authorization alone does not authorize
+  pushing. When already authorized, complete validation and delivery without asking again.
+- For requested updates, fetch before comparing branches; fast-forward only when
+  ancestry and local changes permit it. After pushing, verify HEAD, the tracking ref,
+  and live remote branch SHA agree, and report remaining local changes.
+- Lefthook checks matching staged files: Rust format/Clippy, Python Ruff, comparison
+  formatting, manifests, benchmarks/dashboard, and metadata. Hooks may auto-stage
+  formatting; inspect the result. They do not run full Rust/bindings suites or `pip-audit`.
+- Pre-push runs `task preflight`: lint, all-target compilation, Cargo audits,
+  legal/provenance, and metadata validation. Use `--no-verify` only when explicitly
+  necessary; report the bypass and omitted checks.
+- Hosted validation runs on PRs, `v*` tags, and manual dispatch, not ordinary branch
+  pushes. Cache-prime is not validation. Hosted coverage adds the OS/Python matrix,
+  production-load gates, and `pip-audit`; PRs skip the four heavy ignored cases.
+- Inspect the exact failing CI job/log before changing code. Do not merge with a
+  failing security audit. For metadata authentication, use `REPO_ADMIN_TOKEN` with
+  `task repo-metadata`; a hosted `401` requires checking/rotating the Actions secret.
+- Preserve full-SHA action pins and readable version comments. After BLAS target-table
+  or release-workflow changes, run `task ci` or manually dispatch CI before tagging;
+  Windows/Linux cannot validate macOS Apple Silicon BLAS.
+- Tag CI gates crates.io publishing and dispatches PyPI only after validation succeeds.
+  Keep PyPI top-level for Trusted Publishing attestations; publishing workflows must
+  not independently listen to tags. Read [RELEASING.md](RELEASING.md) before releases.
+- R/Julia benchmark workflow coverage belongs in tag/manual runs. `task benchmarks:preflight`
+  includes Rust smoke and R smoke when R/lme4 is installed. Optional tool skips are not passes.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for extended guidance and
+[Taskfile.yml](Taskfile.yml) for less common commands.

{lme_python-0.2.3 → lme_python-0.2.4}/CHANGELOG.md

@@ -5,14 +5,65 @@ All notable changes to this project will be documented in this file.
 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).
 
+## [Unreleased]
+
+## [0.2.4] - 2026-09-10
+
+### Changed
+
+- Rework the Rust API documentation landing page with model-specific entry points,
+  prediction and inference guidance, and explicit published/development version
+  boundaries. Add responsive styling for rustdoc's light, dark, and Ayu themes,
+  shared by docs.rs builds and the local documentation checks.
+
+### Fixed
+
+- Reject likelihood-ratio comparisons that mix ML and REML, use differing or
+  unavailable REML fixed-effects designs, or contain nonfinite deviances. Refit
+  models with ML when comparing different fixed effects; comparisons of REML
+  random-effects structures with identical fixed-effects designs remain supported.
+- Keep coefficient and marginal-mean confidence intervals finite at confidence
+  levels just below one. Reject unavailable/invalid denominator degrees of freedom
+  instead of replacing them with one, and honor valid positive fractional values.
+- Preserve unavailable p-values through Bonferroni, Holm, and Tukey adjustments;
+  Holm retains the original comparison-family size while excluding missing values
+  from its ordering. Invalid Tukey statistics or degrees of freedom remain unavailable.
+- Preserve very small asymptotic p-values in marginal-mean comparisons, multiple
+  comparisons, and robust coefficient tests, and small chi-squared p-values in
+  likelihood-ratio model comparisons.
+- Retain small nonzero contrast weights in Satterthwaite tests instead of treating
+  them as zero when selecting cached single-coefficient results.
+- Make the blocked LMM optimizer objective agree with the final deviance for
+  nested random effects such as `(1 | batch/cask)`. Correct the sparse cross-block
+  transpose and dense Schur subtraction; regression coverage includes ML, REML,
+  zero-variance boundaries, and the converged fit
+  ([#25](https://github.com/x4g4p3x/lme-rs/issues/25)).
+- Keep Satterthwaite and Kenward-Roger contrast tests invariant to very small,
+  very large, or negative rescalings of the same hypothesis.
+- Reduce redundant Kenward-Roger contrast rows to an independent basis so
+  duplicate restrictions and differing row units do not cause singular solves
+  or change the test's degrees of freedom. Reject all-zero contrast matrices.
+- Preserve very small Satterthwaite coefficient and contrast p-values by
+  evaluating upper-tail probabilities directly instead of subtracting from one.
+- Respect observation precision weights in Gamma simulation, with variance
+  proportional to dispersion divided by the observation weight.
+- Reject Gaussian and Gamma simulation when residual variance or dispersion is
+  missing, nonfinite, or invalid, including saturated OLS fits with no estimated
+  residual variance. Zero Gaussian residual variance remains valid and produces
+  noiseless draws; Gamma dispersion must be positive. Apply the same checks to
+  sequential and parallel simulation.
+- Return an error for overflowing simulation index ranges instead of panicking
+  or wrapping indices; the last representable single index remains valid.
+
 ## [0.2.3] - 2026-09-09
 
 ### Fixed
 
 - Preserve offsets and observation weights throughout Satterthwaite and Kenward-Roger inference.
 - Use one Kenward-Roger covariance adjustment for marginal and joint tests, confidence
-  intervals, estimated marginal means, and multiple comparisons; retain precision
-  for very small p-values and reject nonfinite contrast inputs.
+  intervals, estimated marginal means, multiple comparisons, and printed model
+  summaries; retain precision for very small p-values and reject nonfinite
+  contrast inputs.
 - Respect precision weights in observation-level and cluster-robust standard errors.
 - Keep nested grouping labels distinct when components contain underscores or backslashes.
 - Honor requested grouped cross-validation fold counts, accept supported numeric
@@ -20,8 +71,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Preserve predictors and responses named `intercept` in formula models.
 - Reject nonfinite confidence levels and mismatched or missing robust-inference data.
 - Leave uncertainty unavailable when an OLS fit has no residual degrees of freedom.
-
-
 - Preserve formula offsets in population/conditional predictions and OLS fitting.
 - Preserve precision weights in Gaussian simulation and bootstrap refits; weighted
   residual resampling uses standardized residuals.

{lme_python-0.2.3 → lme_python-0.2.4}/CONTRIBUTING.md

@@ -133,6 +133,15 @@ matching scripts. The tag/manual benchmark workflow requires the formatters.
 
 Use [the documentation index](docs/README.md) as the navigation map.
 
+The Rust API landing page comes from [docs/rustdoc.md](docs/rustdoc.md), included
+by [src/lib.rs](src/lib.rs). Its theme extension is
+[docs/rustdoc.css](docs/rustdoc.css). Run `task doc` to build the styled preview
+at `target/doc/lme_rs/index.html`; `task docs:check` also tests its Rust examples
+and intra-doc links. Keep the stylesheet arguments in `Cargo.toml` and the
+shared CI runner aligned. Check light, dark, and Ayu themes and a narrow viewport
+after styling changes. docs.rs builds the published crate, so repository edits
+reach that site with a new release, following [RELEASING.md](RELEASING.md).
+
 | Content | Canonical location |
 |:--------|:-------------------|
 | Introduction and first successful fit | [README.md](README.md) |

{lme_python-0.2.3 → lme_python-0.2.4}/Cargo.lock

@@ -1508,7 +1508,7 @@ checksum = "11d3d7f243d5c5a8b9bb5d6dd2b1602c0cb0b9db1621bafc7ed66e35ff9fe092"
 
 [[package]]
 name = "lme-rs"
-version = "0.2.3"
+version = "0.2.4"
 dependencies = [
  "ahash",
  "anyhow",

{lme_python-0.2.3 → lme_python-0.2.4}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "lme-rs"
-version = "0.2.3"
+version = "0.2.4"
 edition = "2021"
 authors = ["Martin Huck <x4g4p3x@users.noreply.github.com>"]
 description = "Rust port of R's lme4: linear, generalized, and nonlinear mixed-effects models"
@@ -11,6 +11,9 @@ readme = "README.md"
 keywords = ["statistics", "lme4", "mixed-effects", "glmm", "regression"]
 categories = ["science", "mathematics"]
 
+[package.metadata.docs.rs]
+rustdoc-args = ["--extend-css", "docs/rustdoc.css"]
+
 [features]
 # Enables `bench_load_production` (large synthetic workloads; not run by default `cargo bench`).
 slow-production-benches = []

{lme_python-0.2.3 → lme_python-0.2.4}/GUIDE.md

@@ -30,7 +30,7 @@ dependencies to its `Cargo.toml`:
 
 ```toml
 [dependencies]
-lme-rs = "0.2.3"
+lme-rs = "0.2.4"
 polars = { version = "0.46", features = ["csv"] }
 anyhow = "1"
 ```

{lme_python-0.2.3 → lme_python-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lme_python
-Version: 0.2.3
+Version: 0.2.4
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy

{lme_python-0.2.3 → lme_python-0.2.4}/README.md

@@ -52,7 +52,7 @@ Add these dependencies to your application's `Cargo.toml`:
 
 ```toml
 [dependencies]
-lme-rs = "0.2.3"
+lme-rs = "0.2.4"
 polars = { version = "0.46", features = ["csv"] }
 anyhow = "1"
 ```

{lme_python-0.2.3 → lme_python-0.2.4}/REPO_COMPLETION_BY_AREA.md

@@ -6,7 +6,7 @@ This file gives an **evidence-weighted implementation-coverage score** for major
 
 **Last assessed:** 2026-09-09 (full post-refactor Rust/Julia run records current strict-throughput gaps).
 
-**Versions checked:** `lme-rs` **0.2.3** (root [`Cargo.toml`](Cargo.toml)); Python extension **`lme_python` 0.2.3** ([`python/Cargo.toml`](python/Cargo.toml)).
+**Versions checked:** `lme-rs` **0.2.4-dev.0** (root [`Cargo.toml`](Cargo.toml)); Python extension **`lme_python` 0.2.4-dev.0** ([`python/Cargo.toml`](python/Cargo.toml)).
 
 Repository completion is judged on **three** axes, not features alone:
 

{lme_python-0.2.3 → lme_python-0.2.4}/Taskfile.yml

@@ -50,6 +50,11 @@ tasks:
     cmds:
       - '{{.RUN}} completion-check'
 
+  doc:
+    desc: Build the styled Rust API documentation for local preview
+    cmds:
+      - '{{.RUN}} doc'
+
   docs:check:
     desc: Validate Markdown links, Rust examples/doctests, and generated docs
     cmds:

lme_python-0.2.4/docs/rustdoc.css

@@ -0,0 +1,157 @@
+/* Shared by docs.rs and `task doc` / `task docs:check`.
+ * Extend the built-in rustdoc themes without replacing navigation or search.
+ * Keep all fonts and assets local to rustdoc; no remote dependencies.
+ */
+:root {
+    --lme-accent: #08756c;
+    --lme-tint: #f0f8f6;
+    --lme-muted: #536662;
+}
+
+:root[data-theme="dark"] {
+    --lme-accent: #80d9c6;
+    --lme-tint: #253532;
+    --lme-muted: #b4c7c2;
+}
+
+:root[data-theme="ayu"] {
+    --lme-accent: #80ddd2;
+    --lme-tint: #192b2c;
+    --lme-muted: #b0c5c7;
+}
+
+body.rustdoc main .docblock {
+    font-family: "Fira Sans", system-ui, sans-serif;
+    line-height: 1.7;
+}
+
+body.rustdoc main .docblock a {
+    color: var(--lme-accent);
+    text-underline-offset: 0.18em;
+}
+
+body.rustdoc main .docblock a:hover {
+    text-decoration: underline;
+}
+
+body.rustdoc main .docblock h2 {
+    margin-top: 2.2rem;
+    padding-bottom: 0.5rem;
+}
+
+body.rustdoc main .docblock pre {
+    border: 1px solid var(--border-color);
+    border-radius: 8px;
+    padding: 1.1rem;
+    line-height: 1.55;
+}
+
+body.rustdoc main .docblock table {
+    width: 100%;
+    margin: 1rem 0;
+    font-size: 0.95em;
+}
+
+body.rustdoc main .docblock th,
+body.rustdoc main .docblock td {
+    padding: 0.85rem 1rem;
+    vertical-align: top;
+}
+
+.lme-hero {
+    margin: 1.5rem 0 2rem;
+    padding: 1.75rem 2rem;
+    background: var(--lme-tint);
+    border: 1px solid var(--border-color);
+    border-left: 4px solid var(--lme-accent);
+    border-radius: 4px 12px 12px 4px;
+}
+
+.lme-hero .lme-eyebrow {
+    margin: 0 0 0.65rem;
+    color: var(--lme-muted);
+    font-size: 0.75rem;
+    font-weight: 500;
+    letter-spacing: 0.1em;
+    text-transform: uppercase;
+}
+
+.lme-hero .lme-title {
+    margin: 0;
+    font-size: clamp(1.6rem, 3vw, 2.35rem);
+    font-weight: 500;
+    line-height: 1.2;
+    letter-spacing: -0.035em;
+}
+
+.lme-jump {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.6rem;
+    margin-top: 1.35rem;
+}
+
+.lme-jump a {
+    padding: 0.35rem 0.85rem;
+    border: 1px solid var(--lme-accent);
+    border-radius: 6px;
+    font-size: 0.85rem;
+    font-weight: 500;
+}
+
+.lme-pathways {
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: 0.9rem;
+    margin-top: 1rem;
+}
+
+.lme-path {
+    min-width: 0;
+    padding: 1rem 1.2rem;
+    border: 1px solid var(--border-color);
+    border-radius: 8px;
+}
+
+.lme-path p:first-child {
+    margin-top: 0;
+    font-size: 1.1rem;
+}
+
+.lme-path p:last-child {
+    margin-bottom: 0;
+}
+
+.lme-note {
+    margin: 1.25rem 0;
+    padding: 0.1rem 1.25rem;
+    background: var(--lme-tint);
+    border-left: 3px solid var(--lme-accent);
+    border-radius: 0 6px 6px 0;
+}
+
+@media (max-width: 700px) {
+    .lme-hero {
+        padding: 1.25rem;
+    }
+
+    .lme-pathways {
+        grid-template-columns: 1fr;
+    }
+
+    body.rustdoc main .docblock th,
+    body.rustdoc main .docblock td {
+        padding: 0.65rem;
+    }
+}
+
+@media print {
+    .lme-hero,
+    .lme-note {
+        background: transparent;
+    }
+
+    .lme-path {
+        break-inside: avoid;
+    }
+}

lme_python-0.2.4/docs/rustdoc.md

@@ -0,0 +1,131 @@
+Linear, generalized linear, and nonlinear mixed-effects models with
+`lme4`-style formulas and Polars DataFrames.
+
+<div class="lme-hero">
+<p class="lme-eyebrow">lme-rs · Rust API reference</p>
+<p class="lme-title">From formula to fitted model.</p>
+<p>Fit a model, inspect its numerical diagnostics, and choose the prediction or
+inference method that matches your question.</p>
+<nav class="lme-jump" aria-label="Getting started">
+<a href="#choose-a-model">Choose a model</a>
+<a href="#first-fit">First fit</a>
+<a href="#use-the-result">Use the result</a>
+</nav>
+</div>
+
+# Choose a model
+
+<div class="lme-pathways">
+<div class="lme-path">
+
+**Linear regression**
+
+[`lm_df`] fits ordinary least squares from a formula. Use [`lm`] when you already
+have response and design arrays.
+
+</div>
+<div class="lme-path">
+
+**Linear mixed models**
+
+[`lmer`] fits Gaussian mixed models using REML or maximum likelihood.
+[`lmer_weighted`] adds observation precision weights.
+
+</div>
+<div class="lme-path">
+
+**Generalized mixed models**
+
+[`glmer`] fits a selected [`family::Family`]. [`glmer_with_link`] selects the link;
+[`FitDiagnostics`] records the quadrature order actually used.
+
+</div>
+<div class="lme-path">
+
+**Nonlinear mixed models**
+
+[`nlmer`] fits built-in nonlinear mean functions. [`nlmer_with_mean`] accepts a
+custom mean; [`NlmerOptions`] configures fitting.
+
+</div>
+</div>
+
+# First fit
+
+This small example fits a random intercept for each group. The final `true`
+selects REML; use `false` for maximum likelihood.
+
+```
+use lme_rs::lmer;
+use polars::prelude::*;
+
+# fn main() -> anyhow::Result<()> {
+let data = df!(
+    "y" => [
+        10.0, 12.0, 13.0, 15.0,
+         9.0, 11.0, 14.0, 17.0,
+         8.0, 10.0, 12.0, 14.0,
+    ],
+    "x" => [0.0, 1.0, 2.0, 3.0, 0.0, 1.0, 2.0, 3.0,
+            0.0, 1.0, 2.0, 3.0],
+    "group" => ["a", "a", "a", "a", "b", "b", "b", "b",
+                "c", "c", "c", "c"],
+)?;
+
+let fit = lmer("y ~ x + (1 | group)", &data, true)?;
+let population_predictions = fit.predict(&data)?;
+assert_eq!(population_predictions.len(), data.height());
+# Ok(())
+# }
+```
+
+The result is an [`LmeFit`]. Inspect its coefficients, variance estimates, and
+`diagnostics` before interpreting a fit. With [`FitControl`], you can set iteration
+limits, supply starting values, and require numerical convergence through
+[`fit_prepared_with_control`] or [`fit_prepared_glmer_with_control`].
+
+# Use the result
+
+| Your question | API and interpretation |
+| --- | --- |
+| Predictions from fixed effects? | [`LmeFit::predict`] omits group effects. For GLMMs it returns the linear predictor, including any offset. |
+| Predictions for known groups? | [`LmeFit::predict_conditional`] includes stored group effects. Its `allow_new_levels` option controls the fallback for unseen groups. |
+| GLMM response means? | [`LmeFit::predict_response`] and [`LmeFit::predict_conditional_response`] apply the inverse link, with group effects omitted or included respectively. |
+| Confidence intervals? | [`LmeFit::confint`] gives Wald intervals. [`profile_ci`] provides profile-likelihood alternatives and documents supported parameters. |
+| Fixed-effect hypotheses? | [`contrast`] provides Wald F-tests; [`emmeans`] provides reference-grid marginal means and pairwise comparisons. |
+| Compare nested LMMs? | [`anova()`] compares likelihoods. Use the same observations and fit with ML when fixed effects differ; REML comparisons require identical fixed-effects designs. |
+| Assess predictions on held-out groups? | [`cv_grouped`] and [`cv_grouped_glmer`] preserve grouping structure when splitting folds. |
+| Simulate or bootstrap? | [`LmeFit::simulate`] draws responses from fitted conditional means. [`boot_lmer`] and [`boot_glmer`] perform bootstrap refits. |
+
+# Reuse a design
+
+For repeated fits with the same design, start with [`prepare_lmer`] or
+[`prepare_glmer`]. The resulting [`LmerPrepared`] and [`GlmerPrepared`] objects
+retain the design and model metadata. Fit with [`fit_prepared`] or
+[`fit_prepared_glmer`], or replace only the response with
+[`fit_prepared_with_response`] or [`fit_prepared_glmer_with_response`].
+[`LmerWorkspace`] provides reusable buffers for repeated LMM responses.
+
+# Scope and versions
+
+<div class="lme-note">
+
+**Read the documentation for the version you use.**
+
+On docs.rs, the version selector identifies the published crate documented on
+this page. Changes on the repository's development branch appear here only after
+a new crate release. The [development changelog](https://github.com/x4g4p3x/lme-rs/blob/master/CHANGELOG.md)
+separates **Unreleased** changes from published releases.
+
+</div>
+
+Numerical compatibility is established for tested models and reference fixtures.
+Formula syntax, quadrature, and post-fit inference cover a subset of R's mixed-model
+ecosystem; support varies by model and method. See each API's documented limits
+and check fit diagnostics, including approximation warnings.
+
+Continue with the [Rust guide](https://github.com/x4g4p3x/lme-rs/blob/master/GUIDE.md),
+[documentation index](https://github.com/x4g4p3x/lme-rs/blob/master/docs/README.md), or
+[workflow assessment](https://github.com/x4g4p3x/lme-rs/blob/master/USABILITY.md).
+These repository links follow `master`; select the matching release tag when
+reading about a published version. The API index below belongs to this build.

{lme_python-0.2.3 → lme_python-0.2.4}/python/Cargo.lock

@@ -1262,7 +1262,7 @@ checksum = "11d3d7f243d5c5a8b9bb5d6dd2b1602c0cb0b9db1621bafc7ed66e35ff9fe092"
 
 [[package]]
 name = "lme-rs"
-version = "0.2.3"
+version = "0.2.4"
 dependencies = [
  "ahash",
  "anyhow",
@@ -1286,7 +1286,7 @@ dependencies = [
 
 [[package]]
 name = "lme_python"
-version = "0.2.3"
+version = "0.2.4"
 dependencies = [
  "lme-rs",
  "ndarray 0.16.1",

{lme_python-0.2.3 → lme_python-0.2.4}/python/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "lme_python"
-version = "0.2.3"
+version = "0.2.4"
 edition = "2021"
 authors = ["Martin Huck <x4g4p3x@users.noreply.github.com>"]
 description = "Python bindings for lme-rs"

{lme_python-0.2.3 → lme_python-0.2.4}/scripts/ci/lme_ci.py

@@ -220,7 +220,8 @@ def cargo_doctest() -> None:
 def cargo_doc() -> None:
     run(
         ["cargo", "doc", "--no-deps", "--verbose", "--locked"],
-        env={"RUSTDOCFLAGS": "-D warnings"},
+        # Match the stylesheet in package.metadata.docs.rs for local previews.
+        env={"RUSTDOCFLAGS": "-D warnings --extend-css docs/rustdoc.css"},
     )
 
 

{lme_python-0.2.3 → lme_python-0.2.4}/src/bootstrap.rs

@@ -1,4 +1,4 @@
-//! Parametric and residual bootstrap refits for linear mixed models.
+//! Parametric and residual bootstrap refits for LMMs, and parametric refits for GLMMs.
 //!
 //! Mirrors R's `lme4::bootMer` workflow: simulate or resample responses, refit,
 //! and summarize bootstrap draws. Uses [`crate::prepare_lmer`] + [`crate::fit_prepared_with_response`]