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

{openpls_engine-1.0.2 → openpls_engine-1.2.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: openpls-engine
-Version: 1.0.2
-Summary: PLS-SEM compute engine, a maintained fork of plspm-python with advanced analyses (IPMA, PLSpredict, moderation, FIMIX-PLS) and extended metrics (SRMR, d_ULS, HTMT, Q², MGA) powering OpenPLS.
+Version: 1.2.0
+Summary: PLS-SEM compute engine, a maintained fork of plspm-python with advanced analyses (PLSc, IPMA, PLSpredict, moderation, FIMIX-PLS, Gaussian-copula endogeneity) and extended metrics (SRMR, d_ULS, HTMT, HTMT2, Q², MGA) powering OpenPLS.
 Author-email: Johannes Jacob <johannespjacob@gmail.com>
 License: GPL-3.0-or-later
 Project-URL: Homepage, https://github.com/jojacobsen/openpls-engine
@@ -35,6 +35,8 @@ Dynamic: license-file
 [![PyPI version](https://img.shields.io/pypi/v/openpls-engine.svg)](https://pypi.org/project/openpls-engine/)
 [![Python versions](https://img.shields.io/pypi/pyversions/openpls-engine.svg)](https://pypi.org/project/openpls-engine/)
 [![License: GPL-3.0-or-later](https://img.shields.io/badge/license-GPLv3+-blue.svg)](LICENSE)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20509385.svg)](https://doi.org/10.5281/zenodo.20509385)
+[![Validation DOI](https://img.shields.io/badge/validation%20data-10.5281%2Fzenodo.20511533-blue)](https://doi.org/10.5281/zenodo.20511533)
 
 The compute engine behind [OpenPLS](https://openpls.app), a Python 3 library
 for Partial Least Squares Structural Equation Modeling (PLS-SEM).
@@ -42,12 +44,19 @@ for Partial Least Squares Structural Equation Modeling (PLS-SEM).
 `openpls-engine` is a fork of
 [`plspm-python`](https://github.com/googlecloudplatform/plspm-python) by Jez
 Humble (Google). It keeps the original algorithm intact and adds the metrics
-and quality criteria that modern PLS-SEM reporting requires: HTMT, SRMR,
+and quality criteria that modern PLS-SEM reporting requires: HTMT (and
+HTMT2 geometric-mean variant), SRMR,
 d_ULS, adjusted R², BIC, Stone-Geisser Q², Cronbach α, Dijkstra-Henseler ρ,
-multi-group analysis, and a progress-streaming long bootstrap. It also ships
-**advanced** analyses that go beyond what `plspm-python` covers: PLSpredict
-out-of-sample validation, IPMA (Importance-Performance Map Analysis),
-two-stage moderation, FIMIX-PLS finite-mixture segmentation, and a
+VIF (per-indicator and per-predictor), CTA-PLS (confirmatory tetrad
+analysis for reflective measurement), multi-group analysis, and a
+progress-streaming long bootstrap. It also ships
+**advanced** analyses that go beyond what `plspm-python` covers: PLSc
+(consistent PLS, Dijkstra & Henseler 2015) for measurement-error
+attenuation correction in reflective models, PLSpredict out-of-sample
+validation, IPMA (Importance-Performance Map Analysis),
+two-stage moderation, FIMIX-PLS finite-mixture segmentation, the
+Gaussian-copula endogeneity test (Park & Gupta 2012; Hult et al. 2018),
+and a
 **quasi-Newton (BFGS) inner-weighting scheme** and a **Lohmöller PCA
 scheme**, two new alternatives to the classical centroid, factorial, and
 path schemes (five inner-weighting schemes total).
@@ -61,6 +70,18 @@ phase of the roadmap.
 > with reference implementations is tracked in [TODO.md](TODO.md). See
 > [CHANGELOG.md](CHANGELOG.md) for the version history.
 
+## Documentation
+
+Hosted 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 (Plspm, Config, VIF, CTAPLS, PLSc, GaussianCopula, IPMA, PLSpredict, Moderation, FIMIX, MGA, LongBootstrap).
+- [Examples](https://openpls.app/engine/examples/) - runnable snippets for each advanced analysis.
+- [Changelog](https://openpls.app/engine/changelog/) - version history with per-feature notes.
+
 ## Why fork
 
 * Upstream has not seen a release since 2020.
@@ -81,7 +102,7 @@ pip install openpls-engine
 Or pin a specific version for reproducible analyses:
 
 ```sh
-pip install openpls-engine==1.0.2
+pip install openpls-engine==1.2.0
 ```
 
 To work from source instead:

{openpls_engine-1.0.2 → openpls_engine-1.2.0}/README.md

@@ -4,6 +4,8 @@
 [![PyPI version](https://img.shields.io/pypi/v/openpls-engine.svg)](https://pypi.org/project/openpls-engine/)
 [![Python versions](https://img.shields.io/pypi/pyversions/openpls-engine.svg)](https://pypi.org/project/openpls-engine/)
 [![License: GPL-3.0-or-later](https://img.shields.io/badge/license-GPLv3+-blue.svg)](LICENSE)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20509385.svg)](https://doi.org/10.5281/zenodo.20509385)
+[![Validation DOI](https://img.shields.io/badge/validation%20data-10.5281%2Fzenodo.20511533-blue)](https://doi.org/10.5281/zenodo.20511533)
 
 The compute engine behind [OpenPLS](https://openpls.app), a Python 3 library
 for Partial Least Squares Structural Equation Modeling (PLS-SEM).
@@ -11,12 +13,19 @@ for Partial Least Squares Structural Equation Modeling (PLS-SEM).
 `openpls-engine` is a fork of
 [`plspm-python`](https://github.com/googlecloudplatform/plspm-python) by Jez
 Humble (Google). It keeps the original algorithm intact and adds the metrics
-and quality criteria that modern PLS-SEM reporting requires: HTMT, SRMR,
+and quality criteria that modern PLS-SEM reporting requires: HTMT (and
+HTMT2 geometric-mean variant), SRMR,
 d_ULS, adjusted R², BIC, Stone-Geisser Q², Cronbach α, Dijkstra-Henseler ρ,
-multi-group analysis, and a progress-streaming long bootstrap. It also ships
-**advanced** analyses that go beyond what `plspm-python` covers: PLSpredict
-out-of-sample validation, IPMA (Importance-Performance Map Analysis),
-two-stage moderation, FIMIX-PLS finite-mixture segmentation, and a
+VIF (per-indicator and per-predictor), CTA-PLS (confirmatory tetrad
+analysis for reflective measurement), multi-group analysis, and a
+progress-streaming long bootstrap. It also ships
+**advanced** analyses that go beyond what `plspm-python` covers: PLSc
+(consistent PLS, Dijkstra & Henseler 2015) for measurement-error
+attenuation correction in reflective models, PLSpredict out-of-sample
+validation, IPMA (Importance-Performance Map Analysis),
+two-stage moderation, FIMIX-PLS finite-mixture segmentation, the
+Gaussian-copula endogeneity test (Park & Gupta 2012; Hult et al. 2018),
+and a
 **quasi-Newton (BFGS) inner-weighting scheme** and a **Lohmöller PCA
 scheme**, two new alternatives to the classical centroid, factorial, and
 path schemes (five inner-weighting schemes total).
@@ -30,6 +39,18 @@ phase of the roadmap.
 > with reference implementations is tracked in [TODO.md](TODO.md). See
 > [CHANGELOG.md](CHANGELOG.md) for the version history.
 
+## Documentation
+
+Hosted 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 (Plspm, Config, VIF, CTAPLS, PLSc, GaussianCopula, IPMA, PLSpredict, Moderation, FIMIX, MGA, LongBootstrap).
+- [Examples](https://openpls.app/engine/examples/) - runnable snippets for each advanced analysis.
+- [Changelog](https://openpls.app/engine/changelog/) - version history with per-feature notes.
+
 ## Why fork
 
 * Upstream has not seen a release since 2020.
@@ -50,7 +71,7 @@ pip install openpls-engine
 Or pin a specific version for reproducible analyses:
 
 ```sh
-pip install openpls-engine==1.0.2
+pip install openpls-engine==1.2.0
 ```
 
 To work from source instead:

openpls_engine-1.2.0/openpls/copula.py

@@ -0,0 +1,247 @@
+#!/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
+from scipy import stats
+
+import openpls.config as c
+
+
+def _copula_term(x: np.ndarray) -> np.ndarray:
+    """Park & Gupta (2012) Gaussian copula augmentation term.
+
+    Constructs ``P = Phi^{-1}(F_n(x))``, where ``F_n`` is the empirical
+    CDF rescaled to ``(0, 1)`` via ``rank / (n + 1)`` to keep the
+    transformation finite at the boundaries.
+    """
+    n = x.shape[0]
+    if n < 3:
+        raise ValueError("Gaussian copula requires at least 3 observations")
+    ranks = stats.rankdata(x, method="average")
+    u = ranks / (n + 1.0)
+    return stats.norm.ppf(u)
+
+
+def _ols(y: np.ndarray, x: np.ndarray) -> np.ndarray:
+    """OLS coefficient vector for ``y ~ [1, x]``. Returns coefficients
+    excluding the intercept."""
+    n = y.shape[0]
+    design = np.column_stack([np.ones(n), x])
+    beta, *_ = np.linalg.lstsq(design, y, rcond=None)
+    return beta[1:]
+
+
+class GaussianCopula:
+    """Gaussian copula approach for endogeneity in PLS-SEM
+    (Park & Gupta 2012; Hult, Hair, Proksch, Sarstedt, Pinkwart &
+    Ringle 2018).
+
+    For a chosen endogenous latent variable ``Y`` with predecessor LVs
+    ``X_1, ..., X_p``, each suspected endogenous predictor ``X_k`` is
+    augmented in the structural regression with a copula term
+    ``P_k = Phi^{-1}(F_n(X_k))``. A statistically significant copula
+    coefficient ``gamma_k`` indicates that ``X_k`` is correlated with
+    the omitted-variable error and therefore likely endogenous.
+
+    The augmented model::
+
+        Y = beta_0 + sum_j beta_j X_j + sum_{k in suspected} gamma_k P_k + e
+
+    is estimated by OLS on the latent-variable scores. Inference on the
+    copula coefficients is obtained by a non-parametric bootstrap: rows
+    are resampled with replacement, the augmented regression is refit,
+    and the standard error is the empirical standard deviation of the
+    bootstrap distribution. The two-sided p-value uses the normal-
+    approximation ``t = gamma / SE`` and ``p = 2 * (1 - Phi(|t|))``, the
+    same convention used by :class:`.long_bootstrap.LongBootstrap`.
+
+    The procedure assumes the suspected predictor is *non-normal*: the
+    copula term degenerates under a Gaussian regressor because
+    ``Phi^{-1}(F_n(X))`` is then approximately identical to ``X`` itself.
+    Each tested predictor is screened with the Cramér-von Mises test
+    against the empirical-mean / empirical-sd normal distribution and
+    the p-value is reported alongside the coefficient. A small CvM
+    p-value (e.g. ``< 0.05``) means non-normality is supported and the
+    copula approach is admissible (Hult et al. 2018).
+    """
+
+    def __init__(
+        self,
+        config: c.Config,
+        scores: pd.DataFrame,
+        endogenous: str,
+        suspected: list[str] | None = None,
+        n_boot: int = 500,
+        seed: int | None = 42,
+    ):
+        path = config.path()
+        if endogenous not in path.index:
+            raise ValueError(
+                f"endogenous LV {endogenous!r} not found in the structural model"
+            )
+        predictors = [lv for lv in path.columns if path.loc[endogenous, lv] == 1]
+        if not predictors:
+            raise ValueError(
+                f"LV {endogenous!r} has no predecessors; nothing to test"
+            )
+        if suspected is None:
+            suspected = list(predictors)
+        unknown = [lv for lv in suspected if lv not in predictors]
+        if unknown:
+            raise ValueError(
+                f"suspected LVs {unknown!r} are not predecessors of {endogenous!r}"
+            )
+        if n_boot < 50:
+            raise ValueError("n_boot must be at least 50")
+
+        y = scores[endogenous].to_numpy(dtype=float)
+        x_full = scores[predictors].to_numpy(dtype=float)
+        n = y.shape[0]
+
+        copula_terms = {lv: _copula_term(scores[lv].to_numpy(dtype=float)) for lv in suspected}
+
+        normality = {}
+        for lv in suspected:
+            arr = scores[lv].to_numpy(dtype=float)
+            cvm = stats.cramervonmises(
+                arr,
+                "norm",
+                args=(float(arr.mean()), float(arr.std(ddof=1))),
+            )
+            normality[lv] = float(cvm.pvalue)
+
+        augment = np.column_stack([copula_terms[lv] for lv in suspected])
+        design = np.column_stack([x_full, augment])
+        coef_full = _ols(y, design)
+        coef_paths = pd.Series(
+            coef_full[: len(predictors)], index=predictors, name="estimate"
+        )
+        coef_copulas = pd.Series(
+            coef_full[len(predictors) :], index=suspected, name="estimate"
+        )
+
+        rng = np.random.default_rng(seed)
+        boot_copulas = np.empty((n_boot, len(suspected)))
+        for b in range(n_boot):
+            idx = rng.integers(0, n, size=n)
+            try:
+                coef_b = _ols(y[idx], design[idx])
+            except np.linalg.LinAlgError:
+                boot_copulas[b, :] = np.nan
+                continue
+            boot_copulas[b, :] = coef_b[len(predictors) :]
+
+        valid_mask = ~np.isnan(boot_copulas).any(axis=1)
+        boot_valid = boot_copulas[valid_mask]
+        if boot_valid.shape[0] < 50:
+            raise RuntimeError(
+                f"only {boot_valid.shape[0]} bootstrap fits succeeded; "
+                "the augmented regression may be near-singular"
+            )
+
+        se = boot_valid.std(axis=0, ddof=1)
+        with np.errstate(divide="ignore", invalid="ignore"):
+            t_vals = np.where(se > 0, coef_copulas.values / se, np.nan)
+        p_vals = np.where(
+            np.isnan(t_vals), np.nan, 2.0 * (1.0 - stats.norm.cdf(np.abs(t_vals)))
+        )
+
+        coef_table = pd.DataFrame(
+            {
+                "predictor": suspected,
+                "gamma": coef_copulas.values,
+                "boot_se": se,
+                "t": t_vals,
+                "p_value": p_vals,
+                "cvm_p_nonnormal": [normality[lv] for lv in suspected],
+            }
+        )
+
+        self.__endogenous = endogenous
+        self.__predictors = predictors
+        self.__suspected = list(suspected)
+        self.__n_boot = int(boot_valid.shape[0])
+        self.__alpha = 0.05
+        self.__augmented_paths = coef_paths
+        self.__coefficients = coef_table
+
+    def endogenous(self) -> str:
+        """The endogenous LV under test."""
+        return self.__endogenous
+
+    def predictors(self) -> list[str]:
+        """All structural predecessors of the endogenous LV."""
+        return list(self.__predictors)
+
+    def suspected(self) -> list[str]:
+        """Predictors that received a Gaussian-copula augmentation term."""
+        return list(self.__suspected)
+
+    def coefficients(self) -> pd.DataFrame:
+        """Per-predictor copula diagnostics.
+
+        Columns: ``predictor``, ``gamma`` (the copula coefficient in the
+        augmented regression), ``boot_se`` (bootstrap standard error),
+        ``t`` and ``p_value`` (two-sided normal-approximation), and
+        ``cvm_p_nonnormal`` (Cramér-von Mises p-value of the predictor
+        against a normal with its sample mean / sample sd; small means
+        non-normality is supported and the copula approach is
+        admissible).
+        """
+        return self.__coefficients
+
+    def augmented_paths(self) -> pd.Series:
+        """Path coefficients of the endogenous LV's structural equation
+        *with* the copula terms in the model. These are the endogeneity-
+        corrected estimates that should be compared with the original
+        :meth:`Plspm.path_coefficients` to gauge the magnitude of the
+        endogeneity bias.
+        """
+        return self.__augmented_paths
+
+    def summary(self) -> pd.DataFrame:
+        """Per-predictor decision summary.
+
+        Adds a ``decision`` column to :meth:`coefficients`:
+
+        * ``"endogeneity detected"`` if ``p_value <= alpha`` and the
+          Cramér-von Mises non-normality test rejects normality at
+          ``alpha``;
+        * ``"copula not admissible (normal)"`` if the Cramér-von Mises
+          test fails to reject normality at ``alpha`` — the test
+          cannot distinguish endogeneity from a Gaussian regressor;
+        * ``"no endogeneity detected"`` otherwise.
+        """
+        alpha = self.__alpha
+        out = self.__coefficients.copy()
+        decisions: list[str] = []
+        for _, row in out.iterrows():
+            if row["cvm_p_nonnormal"] > alpha:
+                decisions.append("copula not admissible (normal)")
+            elif np.isnan(row["p_value"]):
+                decisions.append("inconclusive")
+            elif row["p_value"] <= alpha:
+                decisions.append("endogeneity detected")
+            else:
+                decisions.append("no endogeneity detected")
+        out["decision"] = decisions
+        return out
+
+    def n_boot(self) -> int:
+        """Number of successful bootstrap iterations used for SE / p."""
+        return self.__n_boot

openpls_engine-1.2.0/openpls/cta.py

@@ -0,0 +1,209 @@
+#!/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/>.
+
+from itertools import combinations
+
+import numpy as np
+import pandas as pd
+
+import openpls.config as c
+from openpls.mode import Mode
+
+
+def _canonical_tetrad(cov: np.ndarray, i: int, j: int, k: int, l: int) -> float:
+    """Canonical tetrad ``s_ij * s_kl - s_ik * s_jl`` for the index quadruple.
+
+    One canonical tetrad is selected per indicator 4-tuple, giving
+    ``C(p, 4)`` non-redundant tetrads per block. For a one-factor (purely
+    reflective) measurement model all such tetrads have expectation zero.
+    """
+    return float(cov[i, j] * cov[k, l] - cov[i, k] * cov[j, l])
+
+
+class CTAPLS:
+    """Confirmatory Tetrad Analysis for PLS (Gudergan, Ringle, Wende & Will 2008).
+
+    Diagnostic for the *outer model*: tests whether reflective (Mode A)
+    specification of each block with four or more indicators is consistent
+    with the data. The procedure relies on Bollen and Ting's (1993)
+    vanishing-tetrad theorem — for a one-factor block every model-implied
+    tetrad of the indicator covariance matrix has expectation zero. Sample
+    tetrads are bootstrapped to obtain two-sided p-values for the null
+    ``H0: tau = 0``; the Holm step-down correction is applied within each
+    block to control the family-wise error rate at ``alpha``. If any tetrad
+    in a block is rejected, the reflective specification is not supported
+    and a formative (Mode B) specification should be considered.
+
+    Only Mode A blocks with at least four indicators are tested. Mode B
+    blocks and reflective blocks with fewer than four indicators are
+    omitted (tetrads are undefined / vacuously satisfied).
+    """
+
+    def __init__(
+        self,
+        config: c.Config,
+        data: pd.DataFrame,
+        n_boot: int = 500,
+        alpha: float = 0.05,
+        seed: int | None = 42,
+    ):
+        if n_boot < 50:
+            raise ValueError(f"n_boot must be >= 50, got {n_boot}")
+        if not 0.0 < alpha < 1.0:
+            raise ValueError(f"alpha must be in (0, 1), got {alpha}")
+        self.__alpha = alpha
+        self.__n_boot = n_boot
+        self.__tetrads, self.__summary = self.__compute(
+            config, data, n_boot, alpha, seed
+        )
+
+    @staticmethod
+    def __compute(
+        config: c.Config,
+        data: pd.DataFrame,
+        n_boot: int,
+        alpha: float,
+        seed: int | None,
+    ) -> tuple[pd.DataFrame, pd.DataFrame]:
+        rng = np.random.default_rng(seed)
+        tetrad_rows: list[dict] = []
+        summary_rows: list[dict] = []
+        for lv in config.path().columns:
+            if config.mode(lv) != Mode.A:
+                continue
+            inds = [mv for mv in config.mvs(lv) if mv in data.columns]
+            if len(inds) < 4:
+                continue
+            block = data[inds].dropna()
+            if block.shape[0] < 10:
+                continue
+            block_np = block.to_numpy(dtype=float)
+            n_obs, p = block_np.shape
+            quads = list(combinations(range(p), 4))
+            m = len(quads)
+            sample_cov = np.cov(block_np, rowvar=False, ddof=1)
+            observed = np.array(
+                [_canonical_tetrad(sample_cov, *quad) for quad in quads]
+            )
+            boot_values = np.empty((n_boot, m), dtype=float)
+            for b in range(n_boot):
+                idx = rng.integers(n_obs, size=n_obs)
+                cov_b = np.cov(block_np[idx, :], rowvar=False, ddof=1)
+                for t, quad in enumerate(quads):
+                    boot_values[b, t] = _canonical_tetrad(cov_b, *quad)
+            ses = boot_values.std(axis=0, ddof=1)
+            # Two-sided percentile p-value under H0: tau = 0. Center the
+            # bootstrap distribution on zero before comparing magnitudes.
+            centered = boot_values - boot_values.mean(axis=0, keepdims=True)
+            p_values = np.mean(
+                np.abs(centered) >= np.abs(observed), axis=0
+            )
+            # Floor at 1/n_boot so log scales and Holm comparisons stay sane.
+            p_values = np.maximum(p_values, 1.0 / n_boot)
+            decisions = CTAPLS.__holm(p_values, alpha)
+            n_rejected = int(sum(d == "reject" for d in decisions))
+            block_decision = (
+                "reflective rejected"
+                if n_rejected > 0
+                else "reflective supported"
+            )
+            for t, quad in enumerate(quads):
+                i, j, k, l = quad
+                tetrad_rows.append(
+                    {
+                        "lv": lv,
+                        "indicators": f"{inds[i]},{inds[j]},{inds[k]},{inds[l]}",
+                        "tetrad": float(observed[t]),
+                        "boot_se": float(ses[t]),
+                        "p_value": float(p_values[t]),
+                        "holm_decision": decisions[t],
+                    }
+                )
+            summary_rows.append(
+                {
+                    "lv": lv,
+                    "n_indicators": len(inds),
+                    "n_tetrads": m,
+                    "n_rejected": n_rejected,
+                    "decision": block_decision,
+                }
+            )
+        tetrads_df = pd.DataFrame(
+            tetrad_rows,
+            columns=[
+                "lv",
+                "indicators",
+                "tetrad",
+                "boot_se",
+                "p_value",
+                "holm_decision",
+            ],
+        )
+        summary_df = pd.DataFrame(
+            summary_rows,
+            columns=[
+                "lv",
+                "n_indicators",
+                "n_tetrads",
+                "n_rejected",
+                "decision",
+            ],
+        )
+        return tetrads_df, summary_df
+
+    @staticmethod
+    def __holm(p_values: np.ndarray, alpha: float) -> list[str]:
+        """Holm step-down rejection given a vector of p-values."""
+        m = len(p_values)
+        order = np.argsort(p_values)
+        decisions = ["fail to reject"] * m
+        for rank, t in enumerate(order):
+            if p_values[t] < alpha / (m - rank):
+                decisions[t] = "reject"
+            else:
+                break
+        return decisions
+
+    def tetrads(self) -> pd.DataFrame:
+        """Per-tetrad results.
+
+        Long format with one row per tested tetrad and columns ``lv``,
+        ``indicators`` (the four indicator names that form the tetrad,
+        comma-separated), ``tetrad`` (observed sample value), ``boot_se``,
+        ``p_value``, and ``holm_decision`` (``"reject"`` /
+        ``"fail to reject"``, after the within-block Holm correction at the
+        configured ``alpha``).
+        """
+        return self.__tetrads
+
+    def summary(self) -> pd.DataFrame:
+        """Per-block CTA-PLS verdict.
+
+        One row per tested Mode A block (≥ 4 indicators) with columns
+        ``lv``, ``n_indicators``, ``n_tetrads``, ``n_rejected``, and
+        ``decision`` (``"reflective supported"`` when no tetrad rejects
+        after Holm correction; ``"reflective rejected"`` otherwise).
+        """
+        return self.__summary
+
+    def alpha(self) -> float:
+        """Family-wise significance level used for the Holm correction."""
+        return self.__alpha
+
+    def n_boot(self) -> int:
+        """Number of bootstrap resamples used to estimate tetrad SEs."""
+        return self.__n_boot