openpls-engine 1.2.0__tar.gz → 1.4.0__tar.gz

openpls_engine-1.4.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: openpls-engine
+Version: 1.4.0
+Summary: PLS-SEM compute engine, a maintained fork of plspm-python with advanced analyses (PLSc, IPMA, PLSpredict, moderation, FIMIX-PLS, Gaussian-copula endogeneity, disjoint two-stage HOC, specific indirect effects) and extended metrics (SRMR, d_ULS, HTMT, HTMT2, Q², MGA, Cohen f², Fornell-Larcker, publication-ready Report) powering OpenPLS.
+Author-email: Johannes Jacob <johannespjacob@gmail.com>
+License: GPL-3.0-or-later
+Project-URL: Homepage, https://github.com/jojacobsen/openpls-engine
+Project-URL: Documentation, https://openpls.app/engine/
+Project-URL: Issues, https://github.com/jojacobsen/openpls-engine/issues
+Project-URL: OpenPLS web app, https://openpls.app
+Project-URL: Upstream (plspm-python), https://github.com/googlecloudplatform/plspm-python
+Keywords: pls-sem,structural-equation-modeling,statistics,pls,sem
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.5
+Requires-Dist: numpy>=1.23
+Requires-Dist: scipy>=1.10
+Requires-Dist: statsmodels>=0.14
+Requires-Dist: scikit-learn>=1.2
+Dynamic: license-file
+
+<p align="center">
+  <img src="assets/logo.svg" alt="openpls engine" width="320">
+</p>
+
+<p align="center">
+  <strong>A modern, maintained Python engine for Partial Least Squares Structural Equation Modeling (PLS-SEM).</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/jojacobsen/openpls-engine/actions/workflows/ci.yml"><img src="https://github.com/jojacobsen/openpls-engine/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://pypi.org/project/openpls-engine/"><img src="https://img.shields.io/pypi/v/openpls-engine.svg" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/openpls-engine/"><img src="https://img.shields.io/pypi/pyversions/openpls-engine.svg" alt="Python versions"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-GPLv3+-blue.svg" alt="License: GPL-3.0-or-later"></a>
+  <a href="https://doi.org/10.5281/zenodo.20509385"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.20509385.svg" alt="DOI"></a>
+  <a href="https://doi.org/10.5281/zenodo.20511533"><img src="https://img.shields.io/badge/validation%20data-10.5281%2Fzenodo.20511533-blue" alt="Validation DOI"></a>
+</p>
+
+<p align="center">
+  <a href="https://openpls.app/engine">Documentation</a>
+  &nbsp;·&nbsp;
+  <a href="https://openpls.app/engine/quickstart/">Quickstart</a>
+  &nbsp;·&nbsp;
+  <a href="https://openpls.app/engine/api/">API reference</a>
+  &nbsp;·&nbsp;
+  <a href="CHANGELOG.md">Changelog</a>
+</p>
+
+---
+
+`openpls-engine` is the compute core behind [OpenPLS](https://openpls.app) and a standalone PyPI package. It is a maintained fork of [`plspm-python`](https://github.com/googlecloudplatform/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](CHANGELOG.md) for the version history.
+
+## Install
+
+```sh
+pip install openpls-engine
+```
+
+Pin a specific version for reproducible analyses:
+
+```sh
+pip install openpls-engine==1.4.0
+```
+
+Or work from source:
+
+```sh
+git clone https://github.com/jojacobsen/openpls-engine.git
+cd openpls-engine
+python3 -m pip install -e .
+```
+
+## Quickstart
+
+```py
+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](https://openpls.app/engine/quickstart/) 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.
+
+**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**](https://openpls.app/engine):
+
+- [Introduction](https://openpls.app/engine/) — what the library does and who it is for.
+- [Installation](https://openpls.app/engine/installation/) — pip and source installs.
+- [Quickstart](https://openpls.app/engine/quickstart/) — end-to-end fit on the satisfaction dataset.
+- [Core concepts](https://openpls.app/engine/concepts/) — PLS-SEM, Mode A/B, inner-weighting schemes, missing-value strategies.
+- [API reference](https://openpls.app/engine/api/) — the full public surface.
+- [Examples](https://openpls.app/engine/examples/) — runnable snippets for each advanced analysis.
+- [Changelog](https://openpls.app/engine/changelog/) — version history with per-feature notes.
+
+## Development
+
+```sh
+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](https://semver.org). 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`](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](https://doi.org/10.5281/zenodo.20509385) and the validation dataset via [10.5281/zenodo.20511533](https://doi.org/10.5281/zenodo.20511533). See [`CITATION.cff`](CITATION.cff) for the structured metadata.
+
+## License
+
+GNU General Public License v3.0, see [LICENSE](LICENSE). Inherited from upstream `plspm-python` (also GPL-3.0).
+
+## Attribution
+
+This project is a fork of [googlecloudplatform/plspm-python](https://github.com/googlecloudplatform/plspm-python) by Jez Humble. The upstream R package [plspm](https://github.com/gastonstat/plspm) by Gaston Sanchez and the [seminr](https://github.com/sem-in-r/seminr) package by Soumya Ray and Nicholas Danks remain the conceptual references for the algorithm. See [ATTRIBUTION.md](ATTRIBUTION.md) for details.
+
+OpenPLS is an independent project and not affiliated with Google.

openpls_engine-1.4.0/README.md

@@ -0,0 +1,134 @@
+<p align="center">
+  <img src="assets/logo.svg" alt="openpls engine" width="320">
+</p>
+
+<p align="center">
+  <strong>A modern, maintained Python engine for Partial Least Squares Structural Equation Modeling (PLS-SEM).</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/jojacobsen/openpls-engine/actions/workflows/ci.yml"><img src="https://github.com/jojacobsen/openpls-engine/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://pypi.org/project/openpls-engine/"><img src="https://img.shields.io/pypi/v/openpls-engine.svg" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/openpls-engine/"><img src="https://img.shields.io/pypi/pyversions/openpls-engine.svg" alt="Python versions"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-GPLv3+-blue.svg" alt="License: GPL-3.0-or-later"></a>
+  <a href="https://doi.org/10.5281/zenodo.20509385"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.20509385.svg" alt="DOI"></a>
+  <a href="https://doi.org/10.5281/zenodo.20511533"><img src="https://img.shields.io/badge/validation%20data-10.5281%2Fzenodo.20511533-blue" alt="Validation DOI"></a>
+</p>
+
+<p align="center">
+  <a href="https://openpls.app/engine">Documentation</a>
+  &nbsp;·&nbsp;
+  <a href="https://openpls.app/engine/quickstart/">Quickstart</a>
+  &nbsp;·&nbsp;
+  <a href="https://openpls.app/engine/api/">API reference</a>
+  &nbsp;·&nbsp;
+  <a href="CHANGELOG.md">Changelog</a>
+</p>
+
+---
+
+`openpls-engine` is the compute core behind [OpenPLS](https://openpls.app) and a standalone PyPI package. It is a maintained fork of [`plspm-python`](https://github.com/googlecloudplatform/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](CHANGELOG.md) for the version history.
+
+## Install
+
+```sh
+pip install openpls-engine
+```
+
+Pin a specific version for reproducible analyses:
+
+```sh
+pip install openpls-engine==1.4.0
+```
+
+Or work from source:
+
+```sh
+git clone https://github.com/jojacobsen/openpls-engine.git
+cd openpls-engine
+python3 -m pip install -e .
+```
+
+## Quickstart
+
+```py
+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](https://openpls.app/engine/quickstart/) 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.
+
+**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**](https://openpls.app/engine):
+
+- [Introduction](https://openpls.app/engine/) — what the library does and who it is for.
+- [Installation](https://openpls.app/engine/installation/) — pip and source installs.
+- [Quickstart](https://openpls.app/engine/quickstart/) — end-to-end fit on the satisfaction dataset.
+- [Core concepts](https://openpls.app/engine/concepts/) — PLS-SEM, Mode A/B, inner-weighting schemes, missing-value strategies.
+- [API reference](https://openpls.app/engine/api/) — the full public surface.
+- [Examples](https://openpls.app/engine/examples/) — runnable snippets for each advanced analysis.
+- [Changelog](https://openpls.app/engine/changelog/) — version history with per-feature notes.
+
+## Development
+
+```sh
+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](https://semver.org). 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`](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](https://doi.org/10.5281/zenodo.20509385) and the validation dataset via [10.5281/zenodo.20511533](https://doi.org/10.5281/zenodo.20511533). See [`CITATION.cff`](CITATION.cff) for the structured metadata.
+
+## License
+
+GNU General Public License v3.0, see [LICENSE](LICENSE). Inherited from upstream `plspm-python` (also GPL-3.0).
+
+## Attribution
+
+This project is a fork of [googlecloudplatform/plspm-python](https://github.com/googlecloudplatform/plspm-python) by Jez Humble. The upstream R package [plspm](https://github.com/gastonstat/plspm) by Gaston Sanchez and the [seminr](https://github.com/sem-in-r/seminr) package by Soumya Ray and Nicholas Danks remain the conceptual references for the algorithm. See [ATTRIBUTION.md](ATTRIBUTION.md) for details.
+
+OpenPLS is an independent project and not affiliated with Google.

{openpls_engine-1.2.0 → openpls_engine-1.4.0}/openpls/bootstrap.py

@@ -26,6 +26,7 @@ import openpls.config as c
 import openpls.inner_model as im
 import openpls.outer_model as om
 from openpls.estimator import Estimator
+from openpls.specific_indirect import specific_indirect_bootstrap
 from openpls.weights import WeightsCalculatorFactory
 
 
@@ -125,6 +126,11 @@ class Bootstrap:
         self.__total_effects = _create_summary(total_effects, inner_model.effects().loc[:, "total"])
         self.__paths = _create_summary(paths, inner_model.effects().loc[:, "direct"])
         self.__loading = _create_summary(loadings, outer_model.model().loc[:, "loading"])
+        # Retain raw per-iteration direct-path samples so specific indirect
+        # effects can be computed as chain products after the fact.
+        self.__raw_paths = paths.reset_index(drop=True)
+        self.__path_coefficients = inner_model.path_coefficients()
+        self.__structural_path = (self.__path_coefficients != 0).astype(int)
 
     def weights(self) -> pd.DataFrame:
         """Outer weights calculated from bootstrap validation."""
@@ -145,3 +151,48 @@ class Bootstrap:
     def loading(self) -> pd.DataFrame:
         """Loadings of manifest variables calculated from bootstrap validation."""
         return self.__loading
+
+    def specific_indirect_effects(
+        self,
+        source: str,
+        target: str,
+        through: list[str] | None = None,
+        alpha: float = 0.05,
+    ) -> pd.DataFrame:
+        """Specific indirect effects with bootstrap percentile CIs.
+
+        Each row reports one mediation chain ``source -> M1 -> ... -> target``
+        and the per-iteration product of its path coefficients summarised
+        as ``original``, ``mean``, ``std.error``, ``perc.lower``,
+        ``perc.upper`` (at level ``1 - alpha``), and the ``t`` statistic
+        (original / SE).
+
+        Args:
+            source: source LV name.
+            target: target LV name.
+            through: explicit mediator chain (e.g. ``["M1", "M2"]``) to
+                evaluate. If ``None`` (default), every indirect chain
+                from ``source`` to ``target`` in the structural model is
+                returned.
+            alpha: two-sided significance level for the percentile CI
+                (default 0.05 → 95% CI).
+
+        Returns:
+            DataFrame indexed by chain label (e.g. ``"A -> M -> Y"``).
+
+        Raises:
+            ValueError: if ``source == target``, if no indirect chain
+                exists, if ``through`` references nonexistent direct
+                edges, or if ``alpha`` is outside ``(0, 1)``.
+            KeyError: if ``source`` or ``target`` is not a latent
+                variable in the model.
+        """
+        return specific_indirect_bootstrap(
+            self.__raw_paths,
+            self.__path_coefficients,
+            self.__structural_path,
+            source,
+            target,
+            through=through,
+            alpha=alpha,
+        )

openpls_engine-1.4.0/openpls/f_squared.py

@@ -0,0 +1,121 @@
+#!/usr/bin/python3
+#
+# Copyright (C) 2026 Johannes Jacob
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+"""Cohen's f² effect size for structural-model predictors.
+
+For every directed edge ``predictor -> endogenous`` in the structural
+model, ``f² = (R²_full − R²_reduced) / (1 − R²_full)`` measures the
+proportionate change in R² when the predictor is removed (Cohen 1988;
+Hair, Hult, Ringle & Sarstedt 2022). Conventional thresholds:
+
+- ``f² >= 0.02`` — small effect
+- ``f² >= 0.15`` — medium effect
+- ``f² >= 0.35`` — large effect
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+import statsmodels.api as sm
+
+from openpls.config import Config
+
+
+def _effect_size(value: float) -> str:
+    if not np.isfinite(value) or value < 0.02:
+        return "none"
+    if value < 0.15:
+        return "small"
+    if value < 0.35:
+        return "medium"
+    return "large"
+
+
+class FSquared:
+    """Cohen's f² effect size per structural-model edge.
+
+    Constructed lazily on first call to :meth:`~openpls.Plspm.f_squared`.
+    For each endogenous LV and each predictor in its structural equation,
+    the LV's OLS is refit on the standardized scores with that predictor
+    removed; the resulting reduced R² is combined with the full R² to
+    give f². Endogenous LVs with a single predictor return f² = R²_full /
+    (1 − R²_full) (reduced model is intercept-only on a standardized
+    response, R²_red = 0).
+    """
+
+    def __init__(
+        self,
+        config: Config,
+        scores: pd.DataFrame,
+        path_coefficients: pd.DataFrame,
+        r_squared: pd.Series,
+    ):
+        path = config.path()
+        rows = []
+        endogenous = path.sum(axis=1).astype(bool)
+        endogenous_lvs = list(endogenous[endogenous].index)
+        for lv in endogenous_lvs:
+            predictors = list(path.loc[lv][path.loc[lv] == 1].index)
+            r2_full = float(r_squared.loc[lv])
+            for predictor in predictors:
+                reduced = [p for p in predictors if p != predictor]
+                if reduced:
+                    exog = sm.add_constant(scores.loc[:, reduced])
+                    r2_red = float(sm.OLS(scores.loc[:, lv], exog).fit().rsquared)
+                else:
+                    r2_red = 0.0
+                if r2_full >= 1.0 - 1e-12:
+                    f2 = np.inf
+                else:
+                    f2 = (r2_full - r2_red) / (1.0 - r2_full)
+                rows.append({
+                    "from": predictor,
+                    "to": lv,
+                    "r_squared_full": r2_full,
+                    "r_squared_reduced": r2_red,
+                    "f_squared": f2,
+                    "effect_size": _effect_size(f2),
+                })
+        self.__table = pd.DataFrame(
+            rows,
+            index=[f"{r['from']} -> {r['to']}" for r in rows],
+        )
+        self.__matrix = self.__build_matrix(path, self.__table)
+
+    @staticmethod
+    def __build_matrix(path: pd.DataFrame, table: pd.DataFrame) -> pd.DataFrame:
+        m = pd.DataFrame(np.nan, index=path.index, columns=path.columns)
+        for _, row in table.iterrows():
+            m.loc[row["to"], row["from"]] = row["f_squared"]
+        return m
+
+    def table(self) -> pd.DataFrame:
+        """Long-format table indexed by ``"predictor -> endogenous"``.
+
+        Columns: ``from``, ``to``, ``r_squared_full``,
+        ``r_squared_reduced``, ``f_squared``, ``effect_size``.
+        """
+        return self.__table
+
+    def matrix(self) -> pd.DataFrame:
+        """Square matrix of f² values mirroring the path matrix.
+
+        Rows are targets (endogenous LVs), columns are sources. Cells
+        without a structural path are ``NaN``.
+        """
+        return self.__matrix

openpls_engine-1.4.0/openpls/fornell_larcker.py

@@ -0,0 +1,125 @@
+#!/usr/bin/python3
+#
+# Copyright (C) 2026 Johannes Jacob
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+"""Fornell-Larcker discriminant-validity criterion.
+
+The classical Fornell and Larcker (1981) check: for each reflective
+(Mode A) latent variable, the square root of its AVE must exceed its
+absolute correlation with every other latent variable. The matrix
+returned here has ``sqrt(AVE)`` on the diagonal and the inter-construct
+correlations off-diagonal. Formative (Mode B) and single-indicator LVs
+receive ``NaN`` on the diagonal because AVE is undefined for them; the
+modern recommendation (Henseler, Ringle and Sarstedt 2015) is to use
+HTMT for discriminant validity, so this criterion is provided alongside
+HTMT, not in place of it.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from openpls.config import Config
+from openpls.mode import Mode
+
+
+def _ave(config: Config, outer_model: pd.DataFrame) -> pd.Series:
+    """AVE per Mode-A LV (matches inner_summary.InnerSummary)."""
+    ave = pd.Series(np.nan, index=config.path().index, name="ave")
+    for lv in list(config.path()):
+        if config.mode(lv) != Mode.A:
+            continue
+        communality = outer_model.loc[:, "communality"].loc[config.mvs(lv)]
+        num = communality.sum()
+        denom = num + (1 - communality).sum()
+        if denom > 0:
+            ave.loc[lv] = num / denom
+    return ave
+
+
+class FornellLarcker:
+    """Fornell-Larcker discriminant-validity matrix and verdict.
+
+    Constructed lazily on first call to
+    :meth:`~openpls.Plspm.fornell_larcker`. The criterion is satisfied
+    for a reflective LV when the diagonal entry ``sqrt(AVE_lv)`` exceeds
+    every absolute off-diagonal entry in the same row.
+    """
+
+    def __init__(
+        self,
+        config: Config,
+        scores: pd.DataFrame,
+        outer_model: pd.DataFrame,
+    ):
+        ave = _ave(config, outer_model)
+        lvs = list(config.path().index)
+        # Inter-LV correlations from the standardized scores.
+        corr = scores.loc[:, lvs].corr()
+        matrix = corr.copy()
+        for lv in lvs:
+            matrix.loc[lv, lv] = float(np.sqrt(ave.loc[lv])) if not np.isnan(ave.loc[lv]) else np.nan
+        self.__matrix = matrix
+        self.__ave = ave
+        self.__summary = self.__build_summary(matrix, ave, lvs)
+
+    @staticmethod
+    def __build_summary(matrix: pd.DataFrame, ave: pd.Series, lvs: list[str]) -> pd.DataFrame:
+        rows = []
+        for lv in lvs:
+            sqrt_ave = matrix.loc[lv, lv]
+            if np.isnan(sqrt_ave):
+                rows.append({
+                    "lv": lv,
+                    "sqrt_ave": np.nan,
+                    "max_abs_corr": np.nan,
+                    "passes": pd.NA,
+                    "note": "no AVE (non Mode-A or single-indicator)",
+                })
+                continue
+            off = matrix.loc[lv, :].drop(lv).abs()
+            max_off = float(off.max()) if len(off) else 0.0
+            rows.append({
+                "lv": lv,
+                "sqrt_ave": float(sqrt_ave),
+                "max_abs_corr": max_off,
+                "passes": bool(sqrt_ave > max_off),
+                "note": "",
+            })
+        return pd.DataFrame(rows).set_index("lv")
+
+    def matrix(self) -> pd.DataFrame:
+        """Square Fornell-Larcker matrix.
+
+        Diagonal: ``sqrt(AVE)`` per LV (``NaN`` for Mode B / single-
+        indicator). Off-diagonal: latent-variable correlations from the
+        standardized scores.
+        """
+        return self.__matrix
+
+    def ave(self) -> pd.Series:
+        """Average Variance Extracted per LV (``NaN`` for Mode B /
+        single-indicator)."""
+        return self.__ave
+
+    def summary(self) -> pd.DataFrame:
+        """Per-LV discriminant-validity verdict.
+
+        Columns: ``sqrt_ave``, ``max_abs_corr``, ``passes`` (boolean,
+        ``NA`` when AVE is undefined), ``note``.
+        """
+        return self.__summary