polca 0.4.0__tar.gz

polca-0.4.0/.clang-format

@@ -0,0 +1,11 @@
+---
+BasedOnStyle: Google
+IndentWidth: 4
+TabWidth: 4
+ColumnLimit: 100
+AccessModifierOffset: -4
+AllowShortFunctionsOnASingleLine: None
+AllowShortIfStatementsOnASingleLine: false
+AllowShortLoopsOnASingleLine: false
+BreakBeforeBraces: Attach
+PointerAlignment: Left

polca-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,99 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # ── Python lint & format (fast, no build) ────────────────────────
+  lint-python:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uvx ruff check .
+      - run: uvx ruff format --check .
+
+  # ── Python type check (needs C++ build) ──────────────────────────
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: sudo apt-get install -y ninja-build
+      - run: uv pip install -e .
+      - run: uvx mypy pypolca/
+
+  # ── C++ format check ─────────────────────────────────────────────
+  lint-cpp:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: |
+          find src -type f \( -name '*.cpp' -o -name '*.h' -o -name '*.hpp' \) \
+            | xargs clang-format-18 --dry-run --Werror
+
+  # ── Build & test matrix ──────────────────────────────────────────
+  test:
+    needs: [lint-python, lint-cpp, typecheck]
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install system deps (Ubuntu)
+        if: runner.os == 'Linux'
+        run: sudo apt-get install -y ninja-build
+
+      - name: Install system deps (macOS)
+        if: runner.os == 'macOS'
+        run: brew install ninja
+
+      - name: Build package
+        run: uv pip install -e .
+
+      - name: Install test deps
+        run: uv pip install pytest pytest-cov scipy
+
+      - name: Run tests with coverage
+        run: uv run pytest --cov=pypolca --cov-report=term-missing tests/
+
+  # ── Build wheels ─────────────────────────────────────────────────
+  build-wheels:
+    needs: test
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v2.22
+        env:
+          CIBW_BUILD: "cp312-*"
+          CIBW_SKIP: "*_i686 *-musllinux*"
+          CIBW_ARCHS_MACOS: "arm64 x86_64"
+          CIBW_TEST_REQUIRES: "pytest"
+          CIBW_TEST_COMMAND: "pytest {package}/tests"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: ./wheelhouse/*.whl

polca-0.4.0/.github/workflows/wheels.yml

@@ -0,0 +1,59 @@
+name: wheels
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build-wheels:
+    name: ${{ matrix.os }} ${{ matrix.arch || 'x64' }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-24.04
+            arch: x86_64
+          - os: macos-latest
+            arch: arm64
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v2.22
+        env:
+          CIBW_BUILD: "cp312-* cp313-*"
+          CIBW_ARCHS: ${{ matrix.arch }}
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}-${{ matrix.arch }}
+          path: wheelhouse/*.whl
+
+  build-sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build --sdist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  publish:
+    needs: [build-wheels, build-sdist]
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    environment: pypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: "*"
+          path: dist
+          merge-multiple: true
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

polca-0.4.0/.gitignore

@@ -0,0 +1,40 @@
+# Build artifacts
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Python
+__pycache__/
+*.py[cod]
+*.so
+*.pyd
+*.dylib
+*.dll
+
+# uv
+.venv/
+uv.lock
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local-only scripts
+rebuild.sh
+
+# Agent instructions (local-only)
+AGENTS.md
+
+.cache/
+package-lock.json
+.cache
+docs/
+compile_commands.json

polca-0.4.0/.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.14.1
+    hooks:
+      - id: mypy
+        args: [--strict, --ignore-missing-imports, pypolca/]
+        additional_dependencies: [numpy, polars]
+        pass_filenames: false
+
+  - repo: https://github.com/pre-commit/mirrors-clang-format
+    rev: v18.1.8
+    hooks:
+      - id: clang-format
+        types_or: [c++, c]

polca-0.4.0/CMakeLists.txt

@@ -0,0 +1,31 @@
+cmake_minimum_required(VERSION 3.18)
+project(pypolca LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+# --- Fetch Eigen3 (header-only) ---
+include(FetchContent)
+FetchContent_Declare(
+    Eigen
+    GIT_REPOSITORY https://gitlab.com/libeigen/eigen.git
+    GIT_TAG        3.4.0
+    GIT_SHALLOW    TRUE
+)
+FetchContent_MakeAvailable(Eigen)
+
+# --- Fetch pybind11 ---
+FetchContent_Declare(
+    pybind11
+    GIT_REPOSITORY https://github.com/pybind/pybind11.git
+    GIT_TAG        v2.12.0
+    GIT_SHALLOW    TRUE
+)
+FetchContent_MakeAvailable(pybind11)
+
+# --- Build C++ code ---
+add_subdirectory(src/cpp)
+
+add_executable(tryout ${CMAKE_SOURCE_DIR}/examples/tryout.cpp)
+target_link_libraries(tryout PRIVATE pypolca_core)

polca-0.4.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.1
+Name: polca
+Version: 0.4.0
+Summary: Polytomous Variable Latent Class Analysis in C++ with Python bindings
+Keywords: latent class analysis,EM algorithm,mixture model
+Author-Email: =?utf-8?q?Marc-Andr=C3=A9_Ch=C3=A9nier?= <marcandrechenier@gmail.com>
+License: GPL-2.0-or-later
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: GNU General Public License v2 or later (GPLv2+)
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.12
+Requires-Dist: numpy>=1.20
+Requires-Dist: polars
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: numpy; extra == "test"
+Requires-Dist: polars; extra == "test"
+Requires-Dist: scipy; extra == "test"
+Description-Content-Type: text/markdown
+
+# pypoLCA
+
+Polytomous variable latent class analysis (LCA) for Python, powered by a C++17 backend. `pypoLCA` is a translation of R's [poLCA](https://github.com/dlinzer/poLCA) package by Drew Linzer and Jeffrey Lewis.
+
+## What is latent class analysis?
+
+LCA is a statistical method that discovers latent (unobserved) categorical variables from a set of nominal responses. The core assumption is that observed responses are mutually independent conditionally on the latent variable — all dependencies between responses flow through the latent structure.
+
+The model identifies two things:
+
+1. The underlying latent classes (e.g., "high-risk" vs. "low-risk" respondents), and
+2. The conditional probabilities of each observed response given each class.
+
+LCA's latent variables are categorical (e.g., *class 1* = "non-cheaters", *class 2* = "chronic cheaters"). This makes LCA the categorical-data analogue of Gaussian Mixture Models (GMM): GMM assumes normally-distributed responses, LCA assumes multinomial responses. Both fit parameters via Expectation-Maximisation (EM). A good tutorial extending EM beyond standard GMM applications is [Gao (2022)](https://teng-gao.github.io/blog/2022/ems/).
+
+### Applications
+
+- **Diagnostic agreement** — LCA estimates rater accuracy without a gold-standard reference. Applied to carcinoma diagnoses by seven pathologists (Uebersax & Grove, 1990; dataset: `carcinoma`).
+- **Political typology** — LCA identifies voter segments from candidate trait ratings. Applied to 2000 ANES survey data (dataset: `election`).
+- **Academic dishonesty** — Latent classes of cheating behavior among students, regressed on GPA covariates (dataset: `cheating`).
+- **Survey attitude clustering** — Uncovering latent opinion groups from social survey responses (McCutcheon, 1987; dataset: `gss82`).
+
+### Latent class regression
+
+LCA can be extended with **covariates** that predict class membership. `pypoLCA` fits latent class regression using the same hybrid EM / Newton-Raphson algorithm as R's `poLCA`. The EM loop alternates expected-posterior and maximisation steps. Response probabilities have a closed-form M-step, which guarantees the standard EM ascent property. Covariate coefficients lack a closed form and are updated within each M-step via Newton-Raphson (NR). Unlike pure EM, the NR step can overshoot and cause a likelihood drop. The implementation detects this and restarts with perturbed starting values (`max_restarts`). In any case, the algorithm finds only a local maximum, so multiple random starts (`nrep`) are recommended.
+
+Standard errors are provided for all parameter estimates (i.e. conditional response probabilities, prior class probabilities, and (when covariates are present) regression coefficients). SEs are computed from the observed information matrix via the outer product of the individual score contributions, then transformed to probability space via the delta method. This matches the approach used by R's `poLCA`.
+
+## Install
+
+```bash
+pip install pypolca
+```
+
+> Until published on PyPI, install from source:
+>
+> ```bash
+> git clone https://github.com/.../pypoLCA.git
+> cd pypoLCA
+> uv pip install -e ".[dev]"
+> ```
+
+## Quick start
+
+```python
+import pypolca as lca
+
+# Load a built-in dataset (a Polars DataFrame)
+df = lca.load_dataset("carcinoma")
+
+# Fit a 2-class model — seven pathologists rating 118 slides
+result = lca.fit("cbind(A, B, C, D, E, F, G) ~ 1", data=df, nclass=2, nrep=5)
+
+# Inspect results
+print(f"Log-likelihood: {result.loglik:.2f}")
+print(f"AIC: {result.aic:.2f}")
+print(f"Iterations: {result.iterations}")
+
+# Class-conditional probabilities for the first item
+print(result.probs[0])       # shape (nclass, n_categories)
+
+# Posterior class membership (N × R)
+print(result.posterior[:5])
+
+# Predicted class for each observation (1-based)
+print(result.predclass[:5])    # 1-based (matching R poLCA convention)
+
+# Standard errors
+print(result.probs_se[0])    # SEs for first item
+print(result.P_se)           # SEs for class priors
+```
+
+**With covariates (latent class regression):**
+
+```python
+df = lca.load_dataset("cheating")
+
+# Cheating behaviours ~ GPA
+result = lca.fit(
+    "cbind(LIEEXAM, LIEPAPER, FRAUD, COPYEXAM) ~ GPA",
+    data=df,
+    nclass=2,
+    nrep=10,
+)
+
+print(result.coeff)          # Regression coefficients (covariates × (classes − 1))
+print(result.coeff_se)       # Standard errors
+print(result.P)              # Population class shares
+```
+
+The formula syntax uses `cbind(var1, var2, ...)` on the left-hand side, or equivalently Python-style `var1 + var2 + ...`. The right-hand side is `~ 1` for intercept-only or `~ cov1 + cov2` for latent class regression. Parsing is handled by a lightweight custom parser (no external formula library).
+
+## Backend
+
+The EM engine and standard error computation are written in C++17 (Eigen for linear algebra), exposed to Python via pybind11. The build system is CMake + scikit-build-core, managed by `uv`. Incremental C++ rebuilds take ~1–2 s with `./rebuild.sh`.
+
+## Benchmarks
+
+Comparison of `pypolca` (C++, with/without SE) vs R's `poLCA` on the `cheating` dataset (N=319, 4 binary items, 2 classes). Timings are means over 20 runs.
+
+| N      | Items | Classes | R poLCA  | pypolca (with SE) | Speed-up | pypolca (no SE) | Speed-up |
+|--------|-------|---------|----------|-------------------|----------|-----------------|----------|
+| 319    | 4     | 2       | —        | —                 | —        | —               | —        |
+| 500    | 5     | 2       | —        | —                 | —        | —               | —        |
+| 2,000  | 5     | 2       | —        | —                 | —        | —               | —        |
+| 10,000 | 5     | 2       | —        | —                 | —        | —               | —        |
+
+> *Results TBD — run `python scripts/benchmark.py` and `python scripts/benchmark_scaling.py` to populate with fresh numbers (requires R with `poLCA` and `jsonlite` installed). Speed-up is relative to R `poLCA`.*
+
+## Datasets
+
+| Dataset    | N     | Manifest items                                       | Covariates             | Source                    |
+|------------|-------|------------------------------------------------------|------------------------|---------------------------|
+| carcinoma  | 118   | A–G (7 binary: no carcinoma / carcinoma)             | —                      | Agresti (2002)            |
+| cheating   | 319   | LIEEXAM, LIEPAPER, FRAUD, COPYEXAM (4 binary)        | GPA                    | R poLCA                   |
+| election   | 1,785 | MORALG–INTELB (12 ordinal: 4-point trait ratings)    | VOTE3, AGE, EDUC, etc. | 2000 ANES                 |
+| gss82      | 1,202 | PURPOSE, ACCURACY, UNDERSTA, COOPERAT (2–3 categories)| —                      | McCutcheon (1987)         |
+| values     | 216   | A–D (4 binary: universalistic / particularistic)     | —                      | R poLCA                   |
+
+## Credits
+
+pypoLCA is a translation of Drew A. Linzer and Jeffrey B. Lewis's R package:
+
+> Linzer, D. A., & Lewis, J. B. (2011). poLCA: An R Package for Polytomous Variable Latent Class Analysis. *Journal of Statistical Software*, 42(10), 1–29. [doi:10.18637/jss.v042.i10](https://doi.org/10.18637/jss.v042.i10)
+
+Built-in datasets and the EM / Newton-Raphson algorithm are taken from the `poLCA` R package, licensed GPL-2.0-or-later.
+
+C++ bindings powered by [pybind11](https://github.com/pybind/pybind11). Linear algebra via [Eigen](https://eigen.tuxfamily.org/).
+
+## Contributing
+
+Contributions are welcome and appreciated. Please keep submissions tight and purposeful. The goal is to keep `pypoLCA` a focused, maintainable package. AI-assisted contributions are fine, but AI use doesn't excuse sloppy or verbose work; review your output before submitting a PR.
+
+## License
+
+GPL-2.0-or-later

polca-0.4.0/README.md

@@ -0,0 +1,136 @@
+# pypoLCA
+
+Polytomous variable latent class analysis (LCA) for Python, powered by a C++17 backend. `pypoLCA` is a translation of R's [poLCA](https://github.com/dlinzer/poLCA) package by Drew Linzer and Jeffrey Lewis.
+
+## What is latent class analysis?
+
+LCA is a statistical method that discovers latent (unobserved) categorical variables from a set of nominal responses. The core assumption is that observed responses are mutually independent conditionally on the latent variable — all dependencies between responses flow through the latent structure.
+
+The model identifies two things:
+
+1. The underlying latent classes (e.g., "high-risk" vs. "low-risk" respondents), and
+2. The conditional probabilities of each observed response given each class.
+
+LCA's latent variables are categorical (e.g., *class 1* = "non-cheaters", *class 2* = "chronic cheaters"). This makes LCA the categorical-data analogue of Gaussian Mixture Models (GMM): GMM assumes normally-distributed responses, LCA assumes multinomial responses. Both fit parameters via Expectation-Maximisation (EM). A good tutorial extending EM beyond standard GMM applications is [Gao (2022)](https://teng-gao.github.io/blog/2022/ems/).
+
+### Applications
+
+- **Diagnostic agreement** — LCA estimates rater accuracy without a gold-standard reference. Applied to carcinoma diagnoses by seven pathologists (Uebersax & Grove, 1990; dataset: `carcinoma`).
+- **Political typology** — LCA identifies voter segments from candidate trait ratings. Applied to 2000 ANES survey data (dataset: `election`).
+- **Academic dishonesty** — Latent classes of cheating behavior among students, regressed on GPA covariates (dataset: `cheating`).
+- **Survey attitude clustering** — Uncovering latent opinion groups from social survey responses (McCutcheon, 1987; dataset: `gss82`).
+
+### Latent class regression
+
+LCA can be extended with **covariates** that predict class membership. `pypoLCA` fits latent class regression using the same hybrid EM / Newton-Raphson algorithm as R's `poLCA`. The EM loop alternates expected-posterior and maximisation steps. Response probabilities have a closed-form M-step, which guarantees the standard EM ascent property. Covariate coefficients lack a closed form and are updated within each M-step via Newton-Raphson (NR). Unlike pure EM, the NR step can overshoot and cause a likelihood drop. The implementation detects this and restarts with perturbed starting values (`max_restarts`). In any case, the algorithm finds only a local maximum, so multiple random starts (`nrep`) are recommended.
+
+Standard errors are provided for all parameter estimates (i.e. conditional response probabilities, prior class probabilities, and (when covariates are present) regression coefficients). SEs are computed from the observed information matrix via the outer product of the individual score contributions, then transformed to probability space via the delta method. This matches the approach used by R's `poLCA`.
+
+## Install
+
+```bash
+pip install pypolca
+```
+
+> Until published on PyPI, install from source:
+>
+> ```bash
+> git clone https://github.com/.../pypoLCA.git
+> cd pypoLCA
+> uv pip install -e ".[dev]"
+> ```
+
+## Quick start
+
+```python
+import pypolca as lca
+
+# Load a built-in dataset (a Polars DataFrame)
+df = lca.load_dataset("carcinoma")
+
+# Fit a 2-class model — seven pathologists rating 118 slides
+result = lca.fit("cbind(A, B, C, D, E, F, G) ~ 1", data=df, nclass=2, nrep=5)
+
+# Inspect results
+print(f"Log-likelihood: {result.loglik:.2f}")
+print(f"AIC: {result.aic:.2f}")
+print(f"Iterations: {result.iterations}")
+
+# Class-conditional probabilities for the first item
+print(result.probs[0])       # shape (nclass, n_categories)
+
+# Posterior class membership (N × R)
+print(result.posterior[:5])
+
+# Predicted class for each observation (1-based)
+print(result.predclass[:5])    # 1-based (matching R poLCA convention)
+
+# Standard errors
+print(result.probs_se[0])    # SEs for first item
+print(result.P_se)           # SEs for class priors
+```
+
+**With covariates (latent class regression):**
+
+```python
+df = lca.load_dataset("cheating")
+
+# Cheating behaviours ~ GPA
+result = lca.fit(
+    "cbind(LIEEXAM, LIEPAPER, FRAUD, COPYEXAM) ~ GPA",
+    data=df,
+    nclass=2,
+    nrep=10,
+)
+
+print(result.coeff)          # Regression coefficients (covariates × (classes − 1))
+print(result.coeff_se)       # Standard errors
+print(result.P)              # Population class shares
+```
+
+The formula syntax uses `cbind(var1, var2, ...)` on the left-hand side, or equivalently Python-style `var1 + var2 + ...`. The right-hand side is `~ 1` for intercept-only or `~ cov1 + cov2` for latent class regression. Parsing is handled by a lightweight custom parser (no external formula library).
+
+## Backend
+
+The EM engine and standard error computation are written in C++17 (Eigen for linear algebra), exposed to Python via pybind11. The build system is CMake + scikit-build-core, managed by `uv`. Incremental C++ rebuilds take ~1–2 s with `./rebuild.sh`.
+
+## Benchmarks
+
+Comparison of `pypolca` (C++, with/without SE) vs R's `poLCA` on the `cheating` dataset (N=319, 4 binary items, 2 classes). Timings are means over 20 runs.
+
+| N      | Items | Classes | R poLCA  | pypolca (with SE) | Speed-up | pypolca (no SE) | Speed-up |
+|--------|-------|---------|----------|-------------------|----------|-----------------|----------|
+| 319    | 4     | 2       | —        | —                 | —        | —               | —        |
+| 500    | 5     | 2       | —        | —                 | —        | —               | —        |
+| 2,000  | 5     | 2       | —        | —                 | —        | —               | —        |
+| 10,000 | 5     | 2       | —        | —                 | —        | —               | —        |
+
+> *Results TBD — run `python scripts/benchmark.py` and `python scripts/benchmark_scaling.py` to populate with fresh numbers (requires R with `poLCA` and `jsonlite` installed). Speed-up is relative to R `poLCA`.*
+
+## Datasets
+
+| Dataset    | N     | Manifest items                                       | Covariates             | Source                    |
+|------------|-------|------------------------------------------------------|------------------------|---------------------------|
+| carcinoma  | 118   | A–G (7 binary: no carcinoma / carcinoma)             | —                      | Agresti (2002)            |
+| cheating   | 319   | LIEEXAM, LIEPAPER, FRAUD, COPYEXAM (4 binary)        | GPA                    | R poLCA                   |
+| election   | 1,785 | MORALG–INTELB (12 ordinal: 4-point trait ratings)    | VOTE3, AGE, EDUC, etc. | 2000 ANES                 |
+| gss82      | 1,202 | PURPOSE, ACCURACY, UNDERSTA, COOPERAT (2–3 categories)| —                      | McCutcheon (1987)         |
+| values     | 216   | A–D (4 binary: universalistic / particularistic)     | —                      | R poLCA                   |
+
+## Credits
+
+pypoLCA is a translation of Drew A. Linzer and Jeffrey B. Lewis's R package:
+
+> Linzer, D. A., & Lewis, J. B. (2011). poLCA: An R Package for Polytomous Variable Latent Class Analysis. *Journal of Statistical Software*, 42(10), 1–29. [doi:10.18637/jss.v042.i10](https://doi.org/10.18637/jss.v042.i10)
+
+Built-in datasets and the EM / Newton-Raphson algorithm are taken from the `poLCA` R package, licensed GPL-2.0-or-later.
+
+C++ bindings powered by [pybind11](https://github.com/pybind/pybind11). Linear algebra via [Eigen](https://eigen.tuxfamily.org/).
+
+## Contributing
+
+Contributions are welcome and appreciated. Please keep submissions tight and purposeful. The goal is to keep `pypoLCA` a focused, maintainable package. AI-assisted contributions are fine, but AI use doesn't excuse sloppy or verbose work; review your output before submitting a PR.
+
+## License
+
+GPL-2.0-or-later

polca-0.4.0/examples/basic_fit.py

@@ -0,0 +1,62 @@
+"""Example: fit a basic latent class model with pypoLCA."""
+
+import numpy as np
+import polars as pl
+
+# Import the low-level C++ bindings directly
+from pypolca._core import Data, fit_em
+
+# --- Create synthetic data ---
+np.random.seed(42)
+N = 500
+
+# 4 manifest variables, each with 3 categories
+J = 4
+K = 3
+
+# True latent class labels
+true_class = np.random.choice([0, 1], size=N, p=[0.4, 0.6])
+
+# Class-conditional response probabilities
+# Class 0: tends to answer 1
+# Class 1: tends to answer 3
+probs_c0 = np.array([0.6, 0.3, 0.1])
+probs_c1 = np.array([0.1, 0.3, 0.6])
+
+y = np.zeros((N, J), dtype=np.int32)
+for i in range(N):
+    for j in range(J):
+        if true_class[i] == 0:
+            y[i, j] = np.random.choice([1, 2, 3], p=probs_c0) + 1  # 1-based
+        else:
+            y[i, j] = np.random.choice([1, 2, 3], p=probs_c1) + 1
+
+# Build Data object
+data = Data()
+data.y = y
+data.x = np.ones((N, 1), dtype=np.float64)  # intercept only (no covariates)
+data.num_choices = [K] * J
+
+# --- Fit model ---
+print("Fitting 2-class LCA model...")
+result = fit_em(data, nclass=2, maxiter=200, tol=1e-8)
+
+print(f"\nConverged: {result.converged}")
+print(f"Iterations: {result.iterations}")
+print(f"Log-likelihood: {result.loglik:.4f}")
+print(f"Class shares: {result.posterior.mean(axis=0)}")
+print(f"Predclass counts: {np.bincount(result.posterior.argmax(axis=1))}")
+
+# --- Try the high-level API ---
+try:
+    from pypolca.api import fit
+
+    df = pl.DataFrame(
+        y,
+        schema=[f"Y{j + 1}" for j in range(J)],
+    )
+    result2 = fit("Y1 + Y2 + Y3 + Y4 ~ 1", df, nclass=2)
+    print(f"\nHigh-level API result: {result2}")
+    print(f"Class shares: {result2.P}")
+except Exception as e:
+    print(f"High-level API not yet functional: {e}")

polca-0.4.0/examples/debug_ylik.py

@@ -0,0 +1,16 @@
+import numpy as np
+
+from pypolca._core import Data, Params, compute_ylik
+
+data = Data()
+data.y = np.array([[1], [2]], dtype=np.int32)  # 1-based
+data.x = np.ones((2, 1), dtype=np.float64)
+data.num_choices = [2]
+
+p = Params()
+# 1 class, 2 categories: vecprobs layout = [class0_cat0, class0_cat1]
+p.vecprobs = np.array([0.3, 0.7], dtype=np.float64)
+p.beta = np.array([], dtype=np.float64)
+
+lik = compute_ylik(data, p, 1)
+print(lik)