pylgm 0.3.0__tar.gz

pylgm-0.3.0/.github/workflows/docs.yml

@@ -0,0 +1,42 @@
+name: docs
+
+# Builds the MkDocs site and deploys it to GitHub Pages on every push to main.
+# One-time setup: enable Pages for the repo with "GitHub Actions" as the source
+# (Settings -> Pages). Site URL: https://ardea00.github.io/pylgm/
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment; don't cancel an in-progress one.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: python -m pip install .[docs]
+      - run: mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

pylgm-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,23 @@
+name: publish
+
+# Publishes to PyPI when a GitHub Release is published. Uses Trusted
+# Publishing (OIDC) -- no API token is stored; PyPI must have a trusted
+# publisher configured for this repo/workflow (one-time setup on pypi.org).
+on:
+  release:
+    types: [published]
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for Trusted Publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: python -m pip install --upgrade build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

pylgm-0.3.0/.github/workflows/test.yml

@@ -0,0 +1,53 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  core:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e ".[dev]"
+      - run: ruff check src tests
+      - run: pytest -q
+
+  release-gate:
+    # Non-editable install exercises the real hatchling build and the console
+    # entry point exactly as `pip install pylgm` would for a released user.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install .
+      - run: pylgm --help
+
+  spark:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "17"
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e ".[dev,spark]"
+      # Spark and Java are provisioned here, so these tests must run unskipped.
+      - run: pytest tests/data/test_spark.py tests/test_model_spark.py -q

pylgm-0.3.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+.superpowers/
+.worktrees/
+site/
+dist/
+validation/

pylgm-0.3.0/LICENSE

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

pylgm-0.3.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.5
+Name: pylgm
+Version: 0.3.0
+Summary: General-purpose latent Gaussian models for Python
+Project-URL: Homepage, https://github.com/Ardea00/pylgm
+Project-URL: Repository, https://github.com/Ardea00/pylgm
+Project-URL: Issues, https://github.com/Ardea00/pylgm/issues
+Author: Andrea Panozzo
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bayesian,inla,laplace approximation,latent gaussian models,statistics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.11
+Requires-Dist: formulaic>=1.1
+Requires-Dist: numpy>=2.0
+Requires-Dist: pandas>=2.2
+Requires-Dist: pyarrow>=17
+Requires-Dist: pydantic>=2.8
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: scipy>=1.14
+Requires-Dist: typer>=0.15
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Provides-Extra: spark
+Requires-Dist: pyspark>=3.5; extra == 'spark'
+Description-Content-Type: text/markdown
+
+# pyLGM
+
+General-purpose **latent Gaussian models** for Python — the model class behind
+INLA. Fit fixed effects, random effects, temporal (RW/AR1) and spatial (CAR)
+structure under Gaussian, Poisson, or Bernoulli likelihoods, from a Pandas (or
+Spark) DataFrame, with exact-Gaussian and Laplace inference engines, empirical
+Bayes / MAP-II hyperparameter estimation, and INLA-style posterior integration.
+
+## Install
+
+```bash
+pip install pylgm
+pip install "pylgm[spark]"   # optional: Spark data boundary
+```
+
+Requires Python ≥ 3.11.
+
+## 30-second example
+
+A Poisson model with a per-region random intercept, fit with the Laplace engine:
+
+```python
+import pandas as pd
+from pylgm import Fixed, IID, LGM, Poisson
+
+# Counts of events per region over time, with a covariate x.
+frame = pd.DataFrame({
+    "region": ["north", "north", "north", "south", "south", "south"],
+    "time":   [1, 2, 3, 1, 2, 3],
+    "x":      [0.0, 0.5, 1.0, 0.0, 0.5, 1.0],
+    "count":  [3, 5, 8, 2, 3, 5],
+})
+
+model = LGM(
+    response="count",
+    likelihood=Poisson(),                                 # canonical log link
+    predictor=Fixed("1 + x")                              # fixed effects
+        + IID("region", index="region", precision=2.0),  # random intercept per region
+    panel=("region",),
+    time="time",
+)
+
+result = model.fit(frame, engine="laplace")
+print("fitted_mean:", result.fitted_mean.round(3).tolist())
+# fitted_mean: [3.254, 4.986, 8.15, 2.201, 3.373, 5.513]
+```
+
+The same model can be declared in YAML and loaded with `pylgm.config.load_model`.
+See the [general LGM example](examples/general_lgm/README.md), which fits the
+same data through both the Python and YAML frontends, and the other 13 runnable
+scripts under [`examples/`](examples/).
+
+## What's in the box
+
+| Area | What you get | Docs |
+|---|---|---|
+| **Likelihoods** | Gaussian (exact), Poisson & Bernoulli (Laplace) | [likelihoods](docs/likelihoods.md) |
+| **Effects** | `Fixed`, `IID`, `RW1`/`RW2`, stationary `AR1` | [effects](docs/effects.md) |
+| **Spatial** | `Besag` (ICAR), `ProperCAR` (with ρ), `BYM2` (with φ) | [spatial effects](docs/spatial-effects.md) |
+| **Hyperparameters** | Empirical Bayes (type-II ML), MAP-II priors, bounds | [empirical bayes](docs/empirical-bayes.md) |
+| **Integration** | INLA-style grid quadrature, simplified/full-Laplace marginals, DIC/WAIC/CPO/PIT | [INLA](docs/inla.md) |
+| **Prediction** | fit-row and out-of-sample `result.predict(new_data)` | [prediction](docs/prediction.md) |
+| **Data boundary** | Pandas, or Spark / Databricks | [spark](docs/spark.md) |
+
+## Documentation
+
+Full docs: **https://ardea00.github.io/pylgm/** — or browse the
+[`docs/`](docs/) folder. Start with the [index](docs/index.md).
+
+## Scope and roadmap
+
+pyLGM 0.3 is a bounded foundation release. What is and isn't in it, and where
+it's going, are documented in the [roadmap](docs/roadmap.md) and the
+[internals / release policy](docs/internals.md) page.
+
+## Development
+
+See [docs/development.md](docs/development.md). License: [MIT](LICENSE).

pylgm-0.3.0/README.md

@@ -0,0 +1,78 @@
+# pyLGM
+
+General-purpose **latent Gaussian models** for Python — the model class behind
+INLA. Fit fixed effects, random effects, temporal (RW/AR1) and spatial (CAR)
+structure under Gaussian, Poisson, or Bernoulli likelihoods, from a Pandas (or
+Spark) DataFrame, with exact-Gaussian and Laplace inference engines, empirical
+Bayes / MAP-II hyperparameter estimation, and INLA-style posterior integration.
+
+## Install
+
+```bash
+pip install pylgm
+pip install "pylgm[spark]"   # optional: Spark data boundary
+```
+
+Requires Python ≥ 3.11.
+
+## 30-second example
+
+A Poisson model with a per-region random intercept, fit with the Laplace engine:
+
+```python
+import pandas as pd
+from pylgm import Fixed, IID, LGM, Poisson
+
+# Counts of events per region over time, with a covariate x.
+frame = pd.DataFrame({
+    "region": ["north", "north", "north", "south", "south", "south"],
+    "time":   [1, 2, 3, 1, 2, 3],
+    "x":      [0.0, 0.5, 1.0, 0.0, 0.5, 1.0],
+    "count":  [3, 5, 8, 2, 3, 5],
+})
+
+model = LGM(
+    response="count",
+    likelihood=Poisson(),                                 # canonical log link
+    predictor=Fixed("1 + x")                              # fixed effects
+        + IID("region", index="region", precision=2.0),  # random intercept per region
+    panel=("region",),
+    time="time",
+)
+
+result = model.fit(frame, engine="laplace")
+print("fitted_mean:", result.fitted_mean.round(3).tolist())
+# fitted_mean: [3.254, 4.986, 8.15, 2.201, 3.373, 5.513]
+```
+
+The same model can be declared in YAML and loaded with `pylgm.config.load_model`.
+See the [general LGM example](examples/general_lgm/README.md), which fits the
+same data through both the Python and YAML frontends, and the other 13 runnable
+scripts under [`examples/`](examples/).
+
+## What's in the box
+
+| Area | What you get | Docs |
+|---|---|---|
+| **Likelihoods** | Gaussian (exact), Poisson & Bernoulli (Laplace) | [likelihoods](docs/likelihoods.md) |
+| **Effects** | `Fixed`, `IID`, `RW1`/`RW2`, stationary `AR1` | [effects](docs/effects.md) |
+| **Spatial** | `Besag` (ICAR), `ProperCAR` (with ρ), `BYM2` (with φ) | [spatial effects](docs/spatial-effects.md) |
+| **Hyperparameters** | Empirical Bayes (type-II ML), MAP-II priors, bounds | [empirical bayes](docs/empirical-bayes.md) |
+| **Integration** | INLA-style grid quadrature, simplified/full-Laplace marginals, DIC/WAIC/CPO/PIT | [INLA](docs/inla.md) |
+| **Prediction** | fit-row and out-of-sample `result.predict(new_data)` | [prediction](docs/prediction.md) |
+| **Data boundary** | Pandas, or Spark / Databricks | [spark](docs/spark.md) |
+
+## Documentation
+
+Full docs: **https://ardea00.github.io/pylgm/** — or browse the
+[`docs/`](docs/) folder. Start with the [index](docs/index.md).
+
+## Scope and roadmap
+
+pyLGM 0.3 is a bounded foundation release. What is and isn't in it, and where
+it's going, are documented in the [roadmap](docs/roadmap.md) and the
+[internals / release policy](docs/internals.md) page.
+
+## Development
+
+See [docs/development.md](docs/development.md). License: [MIT](LICENSE).