stmmlib 0.2.0__tar.gz → 0.2.5__tar.gz

stmmlib-0.2.5/CHANGELOG.md

@@ -0,0 +1,232 @@
+# Changelog
+
+All notable changes to `stmmlib`. Format follows Keep-a-Changelog; versions
+follow Semantic Versioning.
+
+## [0.2.5] - 2026-11-15
+
+### Fixed
+
+- Gaussian flat and SEBLUP models forward `prov_col`/`kab_col` to the fitting
+  core. Custom-named grouping columns are now excluded from the fixed-effect
+  design; before, only the literal names `prov`/`kab` were skipped, so a frame
+  carrying e.g. `provinsi`/`kabupaten` leaked those text columns into `X`
+  (numpy dtype error, or a silently wrong design).
+- A non-numeric response or predictor in a Gaussian fit raises `ValueError`
+  naming the offending column, matching the Beta path, instead of numpy's
+  "could not convert string to float".
+
+### Changed
+
+- `seblup_rao_yu_it` accepts `prov_col`/`kab_col` (default `None`); existing
+  positional calls are unchanged.
+
+### Notes
+
+- Beta fits can differ by roughly `1e-4` in log-likelihood when the caller
+  permutes rows: the standardisation means are summed in frame order, and the
+  auto-prior refit is a threshold branch that can flip near its boundary.
+  Sort the frame before fitting when a bit-stable reproduction matters.
+
+## [0.2.4] - 2026-11-14
+
+### Changed
+
+- Packaging layout only, no behavior change. Output formatting moved into
+  `stmmlib.reporting` (`_common`, `beta`, `normal`) and the MSE bootstrap into
+  `stmmlib.mse` (`_common`, `_beta`, `_gaussian`, `bootstrap`). The flat
+  `stmmlib.output_format*` modules and `stmmlib.mse_bootstrap` remain as
+  compatibility shims, so existing imports keep working. Stale `__pycache__`
+  directories were removed from the source tree.
+- The Beta Laplace engine was split into single-purpose modules under
+  `stmmlib.beta.engine` (likelihood, gradient, hooks, optimize, finalize,
+  hessian, numerics). `stmmlib.beta.solvers` re-exports every previous name,
+  so existing imports keep working. Point estimates and likelihoods are
+  unchanged by the split.
+
+### Fixed
+
+- Gaussian fits are invariant to input row order: `y` and `X` are sorted with
+  the prepared design before fitting instead of keeping caller order.
+- `build_V` uses the time design for `time_scope="global"`. The area-major
+  time block was used for both scopes, so a global AR(1) fit silently ignored
+  the shared time factor.
+- The Gaussian Hessian uses the correct sign and backend, so `se_theta` is
+  available and finite for the IID model.
+- Gaussian, Beta, and Beta-simulation spatial interaction covariances are
+  area-major (`kron(qa, I_T)`). The transposed Kronecker order disagreed with
+  the design matrix.
+- Beta cAIC and `df_hat` use the same precision builder as the fit engine
+  (`build_beta_Q`), so criteria cannot drift from the fitted prior.
+- `predict_interval` on a Beta fit raises `ValueError` when `vcov` is missing
+  instead of returning a point interval that looked like an interval.
+- The fixed-effect intercept SE uses the full delta method, including the
+  covariance between the intercept and the other fixed effects.
+- Gaussian IID BLUP uses `G Z' V^{-1} e` instead of the scaled residual, which
+  is only equivalent for a diagonal `G`.
+
+## [0.2.3] - 2026-11-13
+
+### Changed
+
+- `formula` is now rejected with `NotImplementedError` at the public entry
+  points. It was accepted and silently ignored, so a caller could believe the
+  design matrix matched the formula while it contained every non-skipped
+  column.
+
+### Fixed
+
+- AR(1) models with `time_scope="global"` (M4, M11) exposed `sigma2_u` in the
+  parameter layout while `build_V` and `build_G_time` only read `sigma2_eta`.
+  The likelihood was invariant to the reported variance. The layout now always
+  uses `sigma2_eta` for AR(1), matching `stlmm5lib`. Results for M4 and M11
+  change.
+- M6 and M13 now estimate a separate IID time variance (`sigma2_time`). The
+  time block used to reuse `sigma2_kab`, so the fitted model had one parameter
+  fewer than the registry declares. This matches `stlmm5lib` in R. Results for
+  M6 and M13 change.
+
+### Added
+
+- Parametric bootstrap MSE of the area-level predictor: `mse_ebp(fit)` for
+  Beta and `mse_eblup(fit)` for Gaussian, in `stmmlib/mse_bootstrap.py`.
+  Single layer by design: beta and theta are fixed while generating, the
+  refit re-estimates them, and the target is the realized area mean of the
+  drawn random effects. No second-order bias correction (see the design doc
+  and the thesis method section). Flat models only in v1.
+- CI matrix for Python 3.10 to 3.14 on Linux plus Windows 3.12, and a build
+  job that runs `python -m build` and `twine check`.
+- Golden numeric tests for Beta IID+AR(1), Gaussian SAR+IID, and Gaussian
+  IID+AR(1), captured from 0.2.2.
+- Architecture tests: a file-size ratchet and a ban on cross-family imports.
+
+## [0.2.2] - 2026-11-13
+
+### Fixed
+
+- README claims now match the code:
+  - M7/M14 area effect is nested IID, not nested SAR. The Beta path says so
+    explicitly, and the Gaussian nested covariance does not use `W`.
+  - GPU acceleration is PyTorch-only and applies to the Beta inner solves;
+    the Gaussian path stays on CPU.
+  - Removed the spatial block cross-validation claim: the package does not
+    implement it.
+  - Holdout prediction is Beta-only (`ebp_newdata`), and that method rejects
+    nested and interaction models.
+  - The quick-start report call uses `summary(strict=True)` and describes the
+    certificate warning accurately.
+  - Citation version and LICENSE link now point at the current release and
+    absolute GitHub URLs, so they work on PyPI.
+
+### Changed
+
+- The `gpu` extra no longer pulls `cupy-cuda12x`; only the PyTorch path is
+  used for acceleration.
+- The sdist now ships `CHANGELOG.md` and `docs/API.md` through `MANIFEST.in`,
+  because the README references the API reference.
+- Added Documentation and Changelog project URLs to the package metadata.
+- The package docstring now describes the actual GPU path (PyTorch/CUDA for
+  the Beta inner solves).
+- License metadata now uses the SPDX expression `MIT` with
+  `setuptools>=77` and no deprecated license classifier.
+
+## [0.2.1] - 2026-11-12
+
+### Fixed
+
+- The Gaussian optimiser's default iteration cap went from 200 to 500. On
+  scipy 1.11 the AR(1) profile likelihood needs 223 iterations (scipy 1.18
+  needs 196), so the old default reported not-converged for a fit that does
+  converge. An explicit `max_iter` is still honoured exactly: the fit then
+  reports not-converged rather than running past the cap.
+
+### Changed
+
+- Installation section now states that `pip install stmmlib` pulls NumPy,
+  SciPy and pandas automatically, notes that the `dev` extra needs a source
+  checkout because the tests are not part of the wheel, and gives a
+  one-line verification command.
+- Version moved to 0.2.1 so a rebuild from this branch cannot collide with
+  the published 0.2.0 filenames on PyPI.
+
+## [0.2.0] - 2026-11-11
+
+### Added
+
+- Fixed-effect inference in both families. Wald is the default; a
+  restricted-refit likelihood ratio test is available with
+  `inference="lrt"` and `lrt_terms=[...]`.
+  - Beta: `stmm(..., family="beta", inference="lrt")` or the universal
+    entry point `stmmlib.beta.lrt_fixed.lrt_fixed_effects(fit, data, terms=...)`;
+    supports `lrt_deadline_s` and `method="refine"` (Newton ascent on the
+    restricted model) or `method="plain"` (re-runs the solver's own
+    optimiser). A refit that does not reach the restricted maximum does not
+    report a p-value.
+  - Gaussian: same API. Likelihoods are compared with ML (REML
+    likelihoods are not comparable across fixed-effects designs); the
+    caller's REML fit is untouched. The certificate is the likelihood:
+    two independent starts must agree, and the restricted likelihood may
+    not exceed the full one. The fixed-effects table shows variable
+    names (not `beta_0`) and, in LRT mode, p (LRT) with the Wald p-value
+    kept at `fit["inference"]["pvalue_wald"]`.
+- Gaussian fits now carry `coef_names` (real predictor names), `x_cols`,
+  `X`, `y`, `model`, `lrt_family` — the Gaussian tables are readable.
+- Convergence certificate for the Beta family: `fit.certificate`
+  (`valid`, `optimum_valid`, `grad_norm`, `hessian_pd`, `near_pd_applied`).
+  `fit.summary(strict=True)` hides Wald inference when the certificate is
+  not inference-grade.
+- Input guards: Beta response outside (0,1) or NaN predictors raise at the
+  door; unbalanced panels warn; non-contiguous area/time codes raise; W
+  ordering is warned about.
+- Suite doubles to 150+ tests (inference switch, LRT both families, input
+  guards, universal API, Satterthwaite honesty).
+
+### Fixed
+
+- The restricted refit could not find the restricted maximum on the thesis
+  panel (step dominated by bound-active coordinates, then clipped to an
+  empty move). The Newton ascent is now projected onto the KKT active
+  set and the Armijo test uses the realised displacement; all six terms
+  certify `ok` and D agrees with the Wald z\u00b2 statistic.
+- A silently wrong Gaussian model: the seblup and nested paths skipped
+  the literal `"y"` while the response is read from `response_col`, so any
+  other response name made the response a predictor of itself. The skip
+  list now comes from the names actually in use.
+- A predictor literally named `prov` or `kab` was silently dropped by the
+  grouping-column convention in both families; the paths now warn and say
+  how to rename it.
+- The Beta summary printed "efek-waktu 11 level" in every report (a
+  literal from one panel). It now prints the fitted number of periods.
+- `df_method="satterthwaite"` is honest: it warns that it uses residual
+  degrees of freedom and documents the `df_method="normal"` alternative.
+- A predictor named `y` now raises a clear collision error instead of a
+  misleading "response must be in (0,1)" message.
+
+### Changed
+
+- `stmm()` validates the family against the model registry:
+  `beta_regression` cannot be fitted as if it were a Gaussian model, and
+  unknown `area`/`time` types raise instead of producing
+  `logLik=nan` / `status=invalid` silently.
+- The registry's `time_scope` is honored by the Gaussian family
+  (previously re-derived from sar+ar1); the seblup and nested families
+  carry it too.
+- Nested Beta models print cAIC / R\u00b2 as `n/a` with the reason
+  (conditional criteria are flat-model only), not a bare `nan`.
+- Comments and docstrings no longer quote thesis measurements; `stmmlib/
+  note/` moved to `docs/notes/`; the package builds clean sdist/wheel.
+- Default LRT behaviour: the untested terms carry NaN p-values under
+  the LRT header; Wald p-values stay available.
+- `beta/__init__.py` documents the actual modules; README is a general
+  reference (not a thesis-bound note), lists both families' LRT and the
+  test-suite workflow.
+
+## [0.1.0] - 2026-11-10
+
+Initial public reference implementation: Gaussian and Beta families, one
+API, 14 model structures (m1-m14) + `beta_regression`, spatial (IID, SAR,
+nested, SEBLUP Rao-Yu) and temporal (IID, AR(1)) random effects, optional
+interactions, Gaussian ML/REML, Beta Laplace-approximated ML, EBLUP/EBP
+prediction, GPU backend via CuPy/PyTorch.
+
+[0.1.0]: initial public reference implementation (2026-11-10).

{stmmlib-0.2.0 → stmmlib-0.2.5}/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Ghardapaty Ghiffary
-
-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.
+MIT License
+
+Copyright (c) 2026 Ghardapaty Ghiffary
+
+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.

stmmlib-0.2.5/MANIFEST.in

@@ -0,0 +1,2 @@
+include CHANGELOG.md
+include docs/API.md