openpls-engine 1.7.0

A modern, maintained Python engine for Partial Least Squares Structural Equation Modeling (PLS-SEM).

Documentation  ·  Quickstart  ·  API reference  ·  Changelog

openpls-engine is the compute core behind OpenPLS and a standalone PyPI package. It is a maintained fork of plspm-python by Jez Humble (Google), with the original algorithm kept intact and modern PLS-SEM reporting, advanced analyses, and two new inner-weighting schemes layered on top.

Status: stable as of 1.0.0. Public API follows semver. See CHANGELOG.md for the version history.

Install

pip install openpls-engine

Pin a specific version for reproducible analyses:

pip install openpls-engine==1.7.0

Or work from source:

git clone https://github.com/jojacobsen/openpls-engine.git
cd openpls-engine
python3 -m pip install -e .

Quickstart

import pandas as pd
from openpls import Plspm
import openpls.config as c
from openpls.scheme import Scheme
from openpls.mode import Mode

satisfaction = pd.read_csv("tests/data/satisfaction.csv", index_col=0)

structure = c.Structure()
structure.add_path(["IMAG"], ["EXPE", "SAT", "LOY"])
structure.add_path(["EXPE"], ["QUAL", "VAL", "SAT"])
structure.add_path(["QUAL"], ["VAL", "SAT"])
structure.add_path(["VAL"],  ["SAT"])
structure.add_path(["SAT"],  ["LOY"])

config = c.Config(structure.path(), scaled=False)
for lv in ["IMAG", "EXPE", "QUAL", "VAL", "SAT", "LOY"]:
    config.add_lv_with_columns_named(lv, Mode.A, satisfaction, lv.lower())

fit = Plspm(satisfaction, config, Scheme.CENTROID)
print(fit.inner_summary())
print(fit.path_coefficients())
print(fit.report().reliability())  # alpha, rho_A, rho_C, AVE

See the Quickstart guide for the full walkthrough.

What's inside

Quality criteria — HTMT and HTMT2 (geometric-mean refinement, Roemer et al. 2021), SRMR, d_ULS, Cronbach α, Dijkstra-Henseler ρ_A and ρ_C, adjusted R², BIC, Stone-Geisser Q² (blindfolding), Cohen f² effect sizes, Fornell-Larcker discriminant validity, per-indicator and per-predictor VIF, CTA-PLS (confirmatory tetrad analysis for reflective measurement).

Advanced analyses — PLSc (consistent-PLS bias correction, Dijkstra & Henseler 2015), Gaussian-copula endogeneity test (Park & Gupta 2012; Hult et al. 2018), disjoint two-stage higher-order constructs covering all four canonical types (R-R / R-F / F-R / F-F), IPMA (Importance-Performance Map Analysis), PLSpredict with the complete Shmueli et al. 2019 panel (RMSE / MAE / MAPE, in-sample + out-of-sample, PLS + LM benchmark), two-stage moderation, FIMIX-PLS finite-mixture segmentation, specific indirect effects with bootstrap percentile CIs, multi-group analysis with Henseler permutation tests, MICOM measurement invariance of composites (Henseler, Ringle & Sarstedt 2016) with three-step verdict.

Engine internals — five inner-weighting schemes (Centroid, Factorial, Path plus the new quasi-Newton/BFGS and Lohmöller PCA schemes), mean-replacement missing-value strategy alongside the upstream casewise default, long-running bootstrap with BCa percentile CIs and progress streaming, publication-ready Plspm.report() that bundles every reviewer-standard panel for one-call export.

Documentation

Full docs at openpls.app/engine:

• Introduction — what the library does and who it is for.
• Installation — pip and source installs.
• Quickstart — end-to-end fit on the satisfaction dataset.
• Core concepts — PLS-SEM, Mode A/B, inner-weighting schemes, missing-value strategies.
• API reference — the full public surface.
• Examples — runnable snippets for each advanced analysis.
• Changelog — version history with per-feature notes.

Development

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt
pip install -e .

pytest          # run the test suite
ruff check .    # lint

CI runs lint and tests on Python 3.10 through 3.13 against every push and pull request against main.

Versioning

openpls-engine follows Semantic Versioning. The public API is stable as of 1.0.0. Tagged releases (vX.Y.Z) trigger a GitHub Actions workflow that builds the package and publishes it to PyPI via OIDC trusted publishing. The version is the single source of truth in pyproject.toml and is exposed at runtime as openpls.__version__. 1.0.0 renamed the import namespace from plspm to openpls; consumers upgrading from 0.7.x must rewrite their imports (see CHANGELOG → Breaking).

Cite

If you use openpls-engine in academic work, please cite the software via its Zenodo DOI and the validation dataset via 10.5281/zenodo.20511533. See CITATION.cff for the structured metadata.

License

GNU General Public License v3.0, see LICENSE. Inherited from upstream plspm-python (also GPL-3.0).

Attribution

This project is a fork of googlecloudplatform/plspm-python by Jez Humble. The upstream R package plspm by Gaston Sanchez and the seminr package by Soumya Ray and Nicholas Danks remain the conceptual references for the algorithm. See ATTRIBUTION.md for details.

OpenPLS is an independent project and not affiliated with Google.