openpls-engine 0.7.0a2__py3-none-any.whl

plspm/fit.py

@@ -0,0 +1,112 @@
+#!/usr/bin/python3
+#
+# Copyright (C) 2026 Johannes Jacob / OpenPLS
+#
+# 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/>.
+
+import numpy as np
+import pandas as pd
+
+import plspm.config as c
+
+
+class ModelFit:
+    """Model-fit indices comparing observed vs model-implied indicator correlations.
+
+    The saturated model-implied correlation is
+
+        Σ̂ = Λ Φ Λᵀ  with diag(Σ̂) = 1
+
+    where Λ is the n × k indicator-loading matrix (one non-zero per row,
+    keyed to the LV the indicator belongs to) and Φ is the k × k LV
+    correlation matrix. SRMR averages squared residuals over the strict
+    lower triangle (the diagonal is forced to 1 by construction);
+    d_ULS is the unweighted sum of those squared residuals.
+
+    See Henseler et al. (2014) for the construction; Henseler et al. (2014)
+    suggest SRMR < 0.08 as an acceptable-fit threshold.
+    """
+
+    def __init__(self, config: c.Config, data: pd.DataFrame, scores: pd.DataFrame, outer_model: pd.DataFrame):
+        # Build the indicator → LV map and the ordered indicator list
+        # following the path-matrix LV order (which is the same order as
+        # `scores.columns` produced by the estimator).
+        lv_names = list(scores.columns)
+        ind_to_lv: dict[str, str] = {}
+        inds: list[str] = []
+        for lv in lv_names:
+            for mv in config.mvs(lv):
+                if mv in data.columns and mv in outer_model.index:
+                    ind_to_lv[mv] = lv
+                    inds.append(mv)
+
+        if len(inds) < 2:
+            self.__srmr = float("nan")
+            self.__d_uls = float("nan")
+            self.__residuals = pd.DataFrame()
+            return
+
+        n_ind, n_lv = len(inds), len(lv_names)
+        loadings = outer_model.loc[inds, "loading"].to_numpy(dtype=float)
+        lv_idx = np.array([lv_names.index(ind_to_lv[i]) for i in inds])
+        Lambda = np.zeros((n_ind, n_lv), dtype=float)
+        Lambda[np.arange(n_ind), lv_idx] = loadings
+
+        Phi = scores.corr().reindex(index=lv_names, columns=lv_names).to_numpy()
+        S = data[inds].corr().to_numpy()
+
+        if np.isnan(Phi).any() or np.isnan(S).any():
+            self.__srmr = float("nan")
+            self.__d_uls = float("nan")
+            self.__residuals = pd.DataFrame()
+            return
+
+        implied = Lambda @ Phi @ Lambda.T
+        np.fill_diagonal(implied, 1.0)
+        resid = S - implied
+
+        iu = np.tril_indices(n_ind, k=-1)
+        self.__srmr = float(np.sqrt(np.mean(resid[iu] ** 2)))
+        self.__d_uls = float(np.sum(resid[iu] ** 2))
+        self.__residuals = pd.DataFrame(resid, index=inds, columns=inds)
+
+    def srmr(self) -> float:
+        """Standardized Root Mean Square Residual.
+
+        ``< 0.08`` is the conventional acceptable-fit threshold
+        (Henseler et al., 2014).
+        """
+        return self.__srmr
+
+    def d_uls(self) -> float:
+        """d_ULS — squared Euclidean distance between observed and
+        model-implied indicator correlation matrices (strict lower triangle).
+        """
+        return self.__d_uls
+
+    def residuals(self) -> pd.DataFrame:
+        """Indicator-correlation residual matrix (observed − model-implied).
+
+        Returns:
+            a square DataFrame indexed by indicator name. Empty if the fit
+            could not be computed (e.g. fewer than two indicators).
+        """
+        return self.__residuals
+
+    def summary(self) -> pd.DataFrame:
+        """One-row summary of the fit indices."""
+        return pd.DataFrame(
+            {"srmr": [self.__srmr], "d_uls": [self.__d_uls]},
+            index=["saturated"],
+        )

plspm/htmt.py

@@ -0,0 +1,119 @@
+#!/usr/bin/python3
+#
+# Copyright (C) 2026 Johannes Jacob / OpenPLS
+#
+# 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/>.
+
+import numpy as np
+import pandas as pd
+
+import plspm.config as c
+
+
+class HTMT:
+    """Heterotrait-Monotrait Ratio of Correlations (Henseler, Ringle & Sarstedt, 2015).
+
+    For each pair ``(i, j)`` of latent variables::
+
+        HTMT(i, j) = mean(|corr(x_i, x_j)|) / sqrt( mean_within(i) * mean_within(j) )
+
+    where ``mean_within`` is the mean of *off-diagonal* absolute correlations
+    among indicators of the same construct. Single-indicator constructs
+    cannot have a within-block mean and are skipped (HTMT is NaN for pairs
+    involving them).
+
+    Henseler et al. (2015) suggest HTMT < 0.85 (conservative) or < 0.90
+    (liberal) as the discriminant-validity threshold.
+    """
+
+    def __init__(self, config: c.Config, data: pd.DataFrame):
+        lv_names = [lv for lv in config.path().columns]
+
+        all_inds: list[str] = []
+        seen: set[str] = set()
+        lv_inds: dict[str, list[str]] = {}
+        for lv in lv_names:
+            inds: list[str] = []
+            for mv in config.mvs(lv):
+                if mv in data.columns:
+                    inds.append(mv)
+                    if mv not in seen:
+                        seen.add(mv)
+                        all_inds.append(mv)
+            lv_inds[lv] = inds
+
+        matrix = pd.DataFrame(np.nan, index=lv_names, columns=lv_names, dtype=float)
+        for lv in lv_names:
+            matrix.loc[lv, lv] = np.nan
+
+        if len(lv_names) < 2 or not all_inds:
+            self.__matrix = matrix
+            return
+
+        corr_abs = data[all_inds].corr().abs()
+
+        def _mean_within(inds: list[str]) -> float | None:
+            valid = [i for i in inds if i in corr_abs.index]
+            if len(valid) < 2:
+                return None
+            sub = corr_abs.loc[valid, valid].to_numpy()
+            n = sub.shape[0]
+            # Off-diagonal upper triangle sum; off-diag count = n*(n-1)/2.
+            return float(np.triu(sub, k=1).sum()) / (n * (n - 1) / 2.0)
+
+        def _mean_between(a: list[str], b: list[str]) -> float | None:
+            va = [i for i in a if i in corr_abs.index]
+            vb = [i for i in b if i in corr_abs.index]
+            if not va or not vb:
+                return None
+            return float(corr_abs.loc[va, vb].to_numpy().mean())
+
+        within = {lv: _mean_within(lv_inds[lv]) for lv in lv_names}
+
+        for i, lv_a in enumerate(lv_names):
+            for lv_b in lv_names[i + 1 :]:
+                mw_a, mw_b = within[lv_a], within[lv_b]
+                if mw_a is None or mw_b is None or mw_a <= 0 or mw_b <= 0:
+                    continue
+                mb = _mean_between(lv_inds[lv_a], lv_inds[lv_b])
+                if mb is None:
+                    continue
+                ratio = mb / float(np.sqrt(mw_a * mw_b))
+                matrix.loc[lv_a, lv_b] = ratio
+                matrix.loc[lv_b, lv_a] = ratio
+
+        self.__matrix = matrix
+
+    def matrix(self) -> pd.DataFrame:
+        """Full symmetric HTMT matrix indexed by latent variable name.
+
+        Diagonal entries are ``NaN`` (HTMT is undefined within a construct).
+        Pairs that involve a single-indicator construct are also ``NaN``.
+        """
+        return self.__matrix
+
+    def pairs(self) -> pd.DataFrame:
+        """Long-format view of the HTMT matrix — one row per unique LV pair.
+
+        Useful for tabular display and CSV export. Columns: ``lv_a``,
+        ``lv_b``, ``htmt``. Pairs with undefined HTMT (NaN) are omitted.
+        """
+        names = list(self.__matrix.index)
+        rows = []
+        for i, lv_a in enumerate(names):
+            for lv_b in names[i + 1 :]:
+                val = self.__matrix.loc[lv_a, lv_b]
+                if pd.notna(val):
+                    rows.append({"lv_a": lv_a, "lv_b": lv_b, "htmt": float(val)})
+        return pd.DataFrame(rows, columns=["lv_a", "lv_b", "htmt"])

plspm/inner_model.py

@@ -0,0 +1,108 @@
+#!/usr/bin/python3
+#
+# Copyright (C) 2019 Google Inc.
+#
+# 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/>.
+
+import pandas as pd
+import statsmodels.api as sm
+
+
+def _summary(dv, regression):
+    summary = pd.DataFrame(0, columns=['from', 'to', 'estimate', 'std error', 't', 'p>|t|'], index=regression.params.index)
+    summary['to'] = dv
+    summary['from'] = regression.params.index
+    summary['estimate'] = regression.params
+    summary['std error'] = regression.bse
+    summary['t'] = regression.tvalues
+    summary['p>|t|'] = regression.pvalues
+    summary['index'] = summary['from'] + " -> " + summary['to']
+    return summary.drop(['const']).reset_index(drop=True)
+
+
+def _effects(path: pd.DataFrame):
+    indirect_paths = pd.DataFrame(0, index=path.index, columns=path.columns)
+    effects = pd.DataFrame({"from":     pd.Series(dtype="str"),
+                            "to":       pd.Series(dtype="str"),
+                            "direct":   pd.Series(dtype="float"),
+                            "indirect": pd.Series(dtype="float"),
+                            "total":    pd.Series(dtype="float")})
+    num_lvs = len(list(path))
+    if (num_lvs == 2):
+        total_paths = path
+    else:
+        path_effects = {}
+        path_effects[0] = path
+        for i in range(1, num_lvs):
+            path_effects[i] = path_effects[i - 1].dot(path)
+            indirect_paths = indirect_paths + path_effects[i]
+        total_paths = path + indirect_paths
+    for from_lv in list(path):
+        for to_lv in list(path):
+            if from_lv != to_lv and total_paths.loc[to_lv, from_lv] != 0:
+                effect = pd.DataFrame([{
+                        "from": from_lv,
+                        "to": to_lv,
+                        "direct": path.loc[to_lv, from_lv],
+                        "indirect": indirect_paths.loc[to_lv, from_lv],
+                        "total": total_paths.loc[to_lv, from_lv]
+                    }], index=[from_lv + " -> " + to_lv])
+                effects = pd.concat([effects, effect])
+    return effects
+
+
+class InnerModel:
+    """Internal class that calculates the attributes of the inner model. Use the methods :meth:`~plspm.Plspm.inner_model`, :meth:`~plspm.Plspm.path_coefficients`, and :meth:`~plspm.Plspm.effects` defined on :class:`~.plspm.Plspm` to retrieve the inner model characteristics."""
+    def __init__(self, path: pd.DataFrame, scores: pd.DataFrame):
+        self.__summaries = None
+        self.__r_squared = pd.Series(0.0, index=path.index, name="r_squared")
+        self.__r_squared_adj = pd.Series(0.0, index=path.index, name="r_squared_adj")
+        self.__path_coefficients = pd.DataFrame(0.0, columns=path.columns, index=path.index)
+        endogenous = path.sum(axis=1).astype(bool)
+        self.__endogenous = list(endogenous[endogenous == True].index)
+        rows = scores.shape[0]
+        for dv in self.__endogenous:
+            ivs = path.loc[dv][path.loc[dv] == 1].index
+            exogenous = sm.add_constant(scores.loc[:, ivs])
+            regression = sm.OLS(scores.loc[:, dv], exogenous).fit()
+            self.__path_coefficients.loc[dv, ivs] = regression.params
+            rsquared = regression.rsquared
+            self.__r_squared.loc[dv] = rsquared
+            self.__r_squared_adj.loc[dv] = 1 - (1 - rsquared) * (rows - 1) / (rows - path.loc[dv].sum() - 1)
+            self.__summaries = pd.concat([self.__summaries, _summary(dv, regression)]).reset_index(drop=True)
+        self.__effects = _effects(self.__path_coefficients)
+
+    def path_coefficients(self) -> pd.DataFrame:
+        """Internal method that returns the path coefficients of the inner model."""
+        return self.__path_coefficients
+
+    def r_squared(self) -> pd.Series:
+        """Internal method that returns r squared for the latent variables."""
+        return self.__r_squared
+
+    def r_squared_adj(self) -> pd.Series:
+        """Internal method that returns adjusted r squared for the latent variables."""
+        return self.__r_squared_adj
+
+    def inner_model(self) -> pd.DataFrame:
+        """Internal method that returns summaries of the characteristics of the inner model for each latent variable."""
+        return self.__summaries.set_index(['index'])
+
+    def effects(self) -> pd.DataFrame:
+        """Internal method that returns indirect, direct, and total effects for each path in the model."""
+        return self.__effects
+
+    def endogenous(self) -> list:
+        """Internal method that returns a list of the endogenous latent variables."""
+        return self.__endogenous

plspm/inner_summary.py

@@ -0,0 +1,79 @@
+#!/usr/bin/python3
+#
+# Copyright (C) 2019 Google Inc.
+#
+# 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/>.
+
+import math
+
+import numpy as np
+import pandas as pd
+
+from plspm.config import Config
+from plspm.mode import Mode
+
+
+class InnerSummary:
+    """Internal class that computes a summary of the inner model.  Use the methods :meth:`~plspm.Plspm.inner_summary` and :meth:`~plspm.Plspm.goodness_of_fit` defined on :class:`~.plspm.Plspm` to retrieve the inner model characteristics."""
+
+    def __init__(self, config: Config, r_squared: pd.Series, r_squared_adj: pd.Series, outer_model: pd.DataFrame,
+                 n_obs: int | None = None):
+        path = config.path()
+        lv_type = path.sum(axis=1).astype(bool)
+        lv_type.name = "type"
+        lv_type_text = lv_type.replace(False, "Exogenous").replace(True, "Endogenous")
+        block_communality = pd.Series(np.nan, index=path.index, name="block_communality")
+        mean_redundancy = pd.Series(np.nan, index=path.index, name="mean_redundancy")
+        ave = pd.Series(np.nan, index=path.index, name="ave")
+        bic = pd.Series(np.nan, index=path.index, name="bic")
+        communality_aux = []
+        num_mvs_in_lv = []
+        for lv in list(config.path()):
+            communality = outer_model.loc[:, "communality"].loc[config.mvs(lv)]
+            block_communality.loc[lv] = communality.mean()
+            mean_redundancy.loc[lv] = outer_model.loc[:, "redundancy"].loc[config.mvs(lv)].mean()
+            if config.mode(lv) == Mode.A:
+                ave_numerator = communality.sum()
+                ave_denominator = ave_numerator + (1 - communality).sum()
+                ave.loc[lv] = ave_numerator / ave_denominator
+            if len(config.mvs(lv)) > 1:
+                num_mvs_in_lv.append(len(config.mvs(lv)))
+                communality_aux.append(block_communality.loc[lv])
+            # BIC for the OLS regression of the standardized LV scores on its
+            # k predictors. SSE = (1 - R²) · (n − 1) since variance(y) = 1.
+            if n_obs is not None:
+                k = int(path.loc[lv].sum())
+                r2 = float(r_squared.loc[lv]) if lv in r_squared.index else 0.0
+                if k > 0 and n_obs > k + 1:
+                    sse = max((1.0 - r2) * (n_obs - 1), 1e-12)
+                    bic.loc[lv] = n_obs * np.log(sse / n_obs) + (k + 1) * np.log(n_obs)
+        self.__summary = pd.concat([lv_type_text, r_squared, r_squared_adj, block_communality, mean_redundancy, ave, bic],
+                                   axis=1, sort=True)
+        if sum(num_mvs_in_lv) > 0:
+            mean_communality = sum(x * y for x, y in zip(communality_aux, num_mvs_in_lv)) / sum(num_mvs_in_lv)
+            r_squared_aux = r_squared * lv_type
+            self.__goodness_of_fit = np.sqrt(mean_communality * r_squared_aux[r_squared_aux != 0].mean())
+        else:
+            # All constructs are single-item so we can't calculate goodness-of-fit
+            self.__goodness_of_fit = float("NaN")
+
+    def summary(self) -> pd.DataFrame:
+        """Internal method that returns the summary of the inner model."""
+        return self.__summary
+
+    def goodness_of_fit(self) -> float:
+        """Internal method that returns the goodness-of-fit of the model."""
+        if math.isnan(self.__goodness_of_fit):
+            raise ValueError("Cannot calculate goodness-of-fit if all constructs are single-item.")
+        return self.__goodness_of_fit