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

{openpls_engine-1.2.0/openpls_engine.egg-info → openpls_engine-1.3.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: openpls-engine
-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.
+Version: 1.3.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) 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
@@ -56,6 +56,8 @@ 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),
+disjoint two-stage higher-order constructs (Sarstedt et al. 2019; Hair
+et al. 2022),
 and a
 **quasi-Newton (BFGS) inner-weighting scheme** and a **Lohmöller PCA
 scheme**, two new alternatives to the classical centroid, factorial, and
@@ -78,7 +80,7 @@ Hosted docs at [**openpls.app/engine**](https://openpls.app/engine):
 - [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).
+- [API reference](https://openpls.app/engine/api/) - the full public surface (Plspm, Config, VIF, CTAPLS, PLSc, GaussianCopula, HigherOrder, 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.
 
@@ -102,7 +104,7 @@ pip install openpls-engine
 Or pin a specific version for reproducible analyses:
 
 ```sh
-pip install openpls-engine==1.2.0
+pip install openpls-engine==1.3.0
 ```
 
 To work from source instead:

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

@@ -25,6 +25,8 @@ 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),
+disjoint two-stage higher-order constructs (Sarstedt et al. 2019; Hair
+et al. 2022),
 and a
 **quasi-Newton (BFGS) inner-weighting scheme** and a **Lohmöller PCA
 scheme**, two new alternatives to the classical centroid, factorial, and
@@ -47,7 +49,7 @@ Hosted docs at [**openpls.app/engine**](https://openpls.app/engine):
 - [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).
+- [API reference](https://openpls.app/engine/api/) - the full public surface (Plspm, Config, VIF, CTAPLS, PLSc, GaussianCopula, HigherOrder, 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.
 
@@ -71,7 +73,7 @@ pip install openpls-engine
 Or pin a specific version for reproducible analyses:
 
 ```sh
-pip install openpls-engine==1.2.0
+pip install openpls-engine==1.3.0
 ```
 
 To work from source instead:

openpls_engine-1.3.0/openpls/higher_order.py

@@ -0,0 +1,291 @@
+#!/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/>.
+
+"""Disjoint two-stage higher-order construct (HOC) workflow for PLS-SEM.
+
+Implements the disjoint two-stage approach recommended by
+Sarstedt, Hair, Cheah, Becker & Ringle (2019) and Hair, Hult, Ringle &
+Sarstedt (2022, A primer on PLS-SEM, 3rd ed., Chapter 8):
+
+1. **Stage 1**: Fit the lower-order model in which the constituent
+   first-order constructs appear as siblings (no second-order LV).
+2. **Stage 2**: Use the standardized first-order LV scores from stage 1
+   as the **indicators** of the second-order construct, and refit a
+   model where the HOC replaces its first-order constructs in the
+   structural part of the model.
+
+This is statistically cleaner than the legacy ``Config.add_higher_order``
+flow (repeated-indicators / embedded two-stage), because in the disjoint
+version the first-order constructs are not simultaneously their own
+measurement and the HOC's predictors. The four canonical HOC types are
+covered via the ``mode`` argument and the modes already set on the
+first-order LVs:
+
+* **Reflective-Reflective (Type I)**: first-order Mode A, HOC Mode A.
+* **Reflective-Formative (Type II)**: first-order Mode A, HOC Mode B.
+* **Formative-Reflective (Type III)**: first-order Mode B, HOC Mode A.
+* **Formative-Formative (Type IV)**: first-order Mode B, HOC Mode B.
+
+References
+----------
+- Sarstedt, M., Hair, J. F., Cheah, J.-H., Becker, J.-M., & Ringle, C. M.
+  (2019). How to specify, estimate, and validate higher-order constructs
+  in PLS-SEM. Australasian Marketing Journal, 27(3), 197-211.
+- Hair, J. F., Hult, G. T. M., Ringle, C. M., & Sarstedt, M. (2022).
+  A primer on partial least squares structural equation modeling
+  (PLS-SEM), 3rd ed., Chapter 8.
+"""
+
+from __future__ import annotations
+
+import pandas as pd
+
+from openpls.config import MV, Config, Structure
+from openpls.mode import Mode
+from openpls.scheme import Scheme
+
+
+def _build_stage2_config(
+    base_config: Config,
+    hoc_name: str,
+    first_order: list[str],
+    hoc_mode: Mode,
+    structure: Structure,
+    score_columns: dict[str, str],
+) -> Config:
+    """Build the stage-2 Config: HOC has the first-order LV scores as
+    indicators; every other LV reuses its original indicators."""
+    stage2_path = structure.path()
+    if hoc_name not in stage2_path.index:
+        raise ValueError(
+            f"HOC {hoc_name!r} does not appear in the stage-2 structure"
+        )
+    for lo in first_order:
+        if lo in stage2_path.index:
+            raise ValueError(
+                f"first-order LV {lo!r} must NOT appear in the stage-2 "
+                f"structure (it has been rolled into {hoc_name!r})"
+            )
+
+    stage2 = Config(stage2_path, scaled=base_config.scaled())
+    for lv in stage2_path.index:
+        if lv == hoc_name:
+            stage2.add_lv(
+                hoc_name,
+                hoc_mode,
+                *[MV(score_columns[lo]) for lo in first_order],
+            )
+            continue
+        if lv not in base_config.path().index:
+            raise ValueError(
+                f"stage-2 LV {lv!r} is not in the base config; HigherOrder "
+                "cannot synthesize indicators for new constructs"
+            )
+        stage2.add_lv(
+            lv,
+            base_config.mode(lv),
+            *[MV(name) for name in base_config.mvs(lv)],
+        )
+    return stage2
+
+
+class HigherOrder:
+    """Disjoint two-stage higher-order construct (Hair et al. 2022).
+
+    The base ``Plspm`` fit serves as **stage 1**. The constructor extracts
+    its scores for the ``first_order`` LVs, appends them as columns to
+    the data, and fits a **stage-2** ``Plspm`` in which:
+
+    * the HOC has the first-order LV scores as its manifest variables
+      (mode = ``mode``), and
+    * every other LV from the base model that still appears in the
+      stage-2 ``structure`` keeps its original indicators.
+
+    The four canonical HOC types are obtained by combining the first-
+    order LV modes (set on ``base_config``) with the HOC ``mode``:
+
+    * Type I  (R-R): first-order A, ``mode=Mode.A``;
+    * Type II (R-F): first-order A, ``mode=Mode.B``;
+    * Type III(F-R): first-order B, ``mode=Mode.A``;
+    * Type IV (F-F): first-order B, ``mode=Mode.B``.
+
+    Parameters
+    ----------
+    base
+        A fitted :class:`.plspm.Plspm` whose LV scores will become the
+        HOC's indicators.
+    name
+        Name of the new second-order construct. Must not collide with an
+        existing LV or with any indicator column in the data.
+    first_order
+        Names of the first-order LVs to roll up. All must exist in the
+        base model and be exposed in ``base.scores()``.
+    mode
+        Mode of the HOC's measurement w.r.t. its first-order indicators.
+    structure
+        :class:`.config.Structure` of the stage-2 path model. Must
+        contain ``name`` and may contain any other LV that was in the
+        base model except the ones listed in ``first_order``.
+    scheme, iterations, tolerance, missing_strategy
+        Passed through to the stage-2 :class:`.plspm.Plspm` fit.
+    """
+
+    def __init__(
+        self,
+        base,
+        name: str,
+        first_order: list[str],
+        mode: Mode,
+        structure: Structure,
+        scheme: Scheme = Scheme.CENTROID,
+        iterations: int = 100,
+        tolerance: float = 1e-6,
+        missing_strategy: str = "casewise",
+    ):
+        from openpls.plspm import Plspm  # avoid circular import
+
+        if not isinstance(base, Plspm):
+            raise TypeError("base must be a fitted Plspm instance")
+        if not isinstance(structure, Structure):
+            raise TypeError("structure must be a Structure instance")
+        if len(first_order) < 2:
+            raise ValueError("a HOC must roll up at least two first-order LVs")
+        if len(set(first_order)) != len(first_order):
+            raise ValueError("first_order contains duplicate LV names")
+
+        base_config = base.config()
+        base_path = base_config.path()
+        for lo in first_order:
+            if lo not in base_path.index:
+                raise ValueError(
+                    f"first-order LV {lo!r} is not in the base model"
+                )
+
+        scores = base.scores()
+        missing_scores = [lo for lo in first_order if lo not in scores.columns]
+        if missing_scores:
+            raise RuntimeError(
+                f"base fit did not produce scores for {missing_scores!r}"
+            )
+
+        if name in base_path.index:
+            raise ValueError(
+                f"HOC name {name!r} clashes with an existing LV in the base model"
+            )
+
+        data = base.data()
+        score_columns: dict[str, str] = {}
+        for lo in first_order:
+            col = f"{name}__{lo}"
+            if col in data.columns:
+                raise ValueError(
+                    f"derived indicator column {col!r} already exists in the "
+                    "original data; choose a different HOC name"
+                )
+            score_columns[lo] = col
+
+        data2 = data.copy()
+        for lo, col in score_columns.items():
+            data2[col] = scores[lo].reindex(data2.index)
+
+        stage2_config = _build_stage2_config(
+            base_config=base_config,
+            hoc_name=name,
+            first_order=first_order,
+            hoc_mode=mode,
+            structure=structure,
+            score_columns=score_columns,
+        )
+
+        refit = Plspm(
+            data2,
+            stage2_config,
+            scheme,
+            iterations=iterations,
+            tolerance=tolerance,
+            missing_strategy=missing_strategy,
+        )
+
+        self.__base = base
+        self.__refit = refit
+        self.__name = name
+        self.__first_order = list(first_order)
+        self.__hoc_mode = mode
+        self.__score_columns = score_columns
+
+    def name(self) -> str:
+        """Name of the higher-order construct."""
+        return self.__name
+
+    def first_order(self) -> list[str]:
+        """The first-order LVs rolled into the HOC."""
+        return list(self.__first_order)
+
+    def hoc_mode(self) -> Mode:
+        """Measurement mode of the HOC w.r.t. its first-order indicators."""
+        return self.__hoc_mode
+
+    def base(self):
+        """The stage-1 ``Plspm`` fit (first-order siblings)."""
+        return self.__base
+
+    def refit(self):
+        """The stage-2 ``Plspm`` fit (HOC in place of its first-order LVs)."""
+        return self.__refit
+
+    def indicator_columns(self) -> dict[str, str]:
+        """Mapping ``first_order_lv -> indicator column name`` used to
+        carry the stage-1 scores into the stage-2 data."""
+        return dict(self.__score_columns)
+
+    def loadings(self) -> pd.Series:
+        """Outer loadings (Mode A) or outer weights (Mode B) of the HOC
+        on its first-order indicators, indexed by first-order LV name."""
+        outer = self.__refit.outer_model()
+        col = "loading" if self.__hoc_mode == Mode.A else "weight"
+        out = pd.Series(index=self.__first_order, dtype=float, name=col)
+        for lo, ind in self.__score_columns.items():
+            out.loc[lo] = float(outer.loc[ind, col])
+        return out
+
+    def path_coefficients(self) -> pd.DataFrame:
+        """Stage-2 structural path coefficients (HOC included)."""
+        return self.__refit.path_coefficients()
+
+    def r_squared(self) -> pd.Series:
+        """Stage-2 R² per endogenous LV (HOC included if endogenous)."""
+        summary = self.__refit.inner_summary()
+        return summary["r_squared"]
+
+    def summary(self) -> pd.DataFrame:
+        """Per-first-order-LV measurement summary of the HOC: loading or
+        weight (depending on ``hoc_mode``), and the stage-1 R² of that
+        first-order LV (NaN for exogenous first-order LVs)."""
+        base_r2 = self.__base.inner_summary()["r_squared"]
+        col = "loading" if self.__hoc_mode == Mode.A else "weight"
+        rows = []
+        for lo in self.__first_order:
+            ind = self.__score_columns[lo]
+            outer = self.__refit.outer_model().loc[ind]
+            rows.append(
+                {
+                    "first_order": lo,
+                    col: float(outer[col]),
+                    "stage1_r_squared": float(base_r2.get(lo, float("nan"))),
+                }
+            )
+        return pd.DataFrame(rows)

{openpls_engine-1.2.0 → openpls_engine-1.3.0}/openpls/plspm.py

@@ -29,6 +29,7 @@ from openpls.cta import CTAPLS
 from openpls.estimator import Estimator
 from openpls.fimix import FIMIX
 from openpls.fit import ModelFit
+from openpls.higher_order import HigherOrder
 from openpls.htmt import HTMT
 from openpls.htmt2 import HTMT2
 from openpls.ipma import IPMA
@@ -142,6 +143,15 @@ class Plspm:
         """
         return self.__scores
 
+    def data(self) -> pd.DataFrame:
+        """The dataset actually used in the fit (after the configured
+        missing-value strategy has been applied)."""
+        return self.__data
+
+    def config(self) -> c.Config:
+        """The :class:`.config.Config` used in the fit."""
+        return self.__config
+
     def outer_model(self) -> pd.DataFrame:
         """Gets the outer model
 
@@ -473,6 +483,55 @@ class Plspm:
             seed=seed,
         )
 
+    def higher_order(
+        self,
+        name: str,
+        first_order: list[str],
+        mode,
+        structure,
+        iterations: int = 100,
+        tolerance: float = 1e-6,
+        missing_strategy: str = "casewise",
+    ) -> HigherOrder:
+        """Disjoint two-stage higher-order construct
+        (Sarstedt et al. 2019; Hair et al. 2022).
+
+        Uses this fit as **stage 1** and fits a **stage-2** model in
+        which ``name`` is a new construct whose indicators are the
+        first-order LV scores produced by stage 1. The four canonical
+        HOC types (R-R, R-F, F-R, F-F) follow from the existing first-
+        order modes in this config plus the ``mode`` chosen here.
+
+        Args:
+            name: name of the second-order construct. Must not collide
+                with an existing LV or data column.
+            first_order: first-order LVs (from this fit) to roll into
+                the HOC. At least two are required.
+            mode: measurement mode of the HOC w.r.t. its first-order
+                indicators (:class:`.mode.Mode`).
+            structure: :class:`.config.Structure` of the stage-2 path
+                model. Must include ``name`` and must NOT include any
+                of the ``first_order`` LVs.
+            iterations, tolerance, missing_strategy: stage-2 ``Plspm``
+                fit options.
+
+        Returns:
+            a :class:`.higher_order.HigherOrder` instance exposing the
+            stage-2 fit (``refit()``) and HOC-specific accessors
+            (``loadings()``, ``summary()``).
+        """
+        return HigherOrder(
+            self,
+            name=name,
+            first_order=first_order,
+            mode=mode,
+            structure=structure,
+            scheme=self.__scheme,
+            iterations=iterations,
+            tolerance=tolerance,
+            missing_strategy=missing_strategy,
+        )
+
     def bootstrap(self) -> Bootstrap:
         """Gets the results of bootstrap validation, if requested
 

{openpls_engine-1.2.0 → openpls_engine-1.3.0/openpls_engine.egg-info}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: openpls-engine
-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.
+Version: 1.3.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) 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
@@ -56,6 +56,8 @@ 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),
+disjoint two-stage higher-order constructs (Sarstedt et al. 2019; Hair
+et al. 2022),
 and a
 **quasi-Newton (BFGS) inner-weighting scheme** and a **Lohmöller PCA
 scheme**, two new alternatives to the classical centroid, factorial, and
@@ -78,7 +80,7 @@ Hosted docs at [**openpls.app/engine**](https://openpls.app/engine):
 - [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).
+- [API reference](https://openpls.app/engine/api/) - the full public surface (Plspm, Config, VIF, CTAPLS, PLSc, GaussianCopula, HigherOrder, 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.
 
@@ -102,7 +104,7 @@ pip install openpls-engine
 Or pin a specific version for reproducible analyses:
 
 ```sh
-pip install openpls-engine==1.2.0
+pip install openpls-engine==1.3.0
 ```
 
 To work from source instead:

{openpls_engine-1.2.0 → openpls_engine-1.3.0}/openpls_engine.egg-info/SOURCES.txt

@@ -9,6 +9,7 @@ openpls/cta.py
 openpls/estimator.py
 openpls/fimix.py
 openpls/fit.py
+openpls/higher_order.py
 openpls/htmt.py
 openpls/htmt2.py
 openpls/inner_model.py
@@ -40,6 +41,7 @@ tests/test_cta.py
 tests/test_estimator.py
 tests/test_fimix.py
 tests/test_fit.py
+tests/test_higher_order.py
 tests/test_htmt.py
 tests/test_htmt2.py
 tests/test_inner_summary_metrics.py

{openpls_engine-1.2.0 → openpls_engine-1.3.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "openpls-engine"
-version = "1.2.0"
-description = "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."
+version = "1.3.0"
+description = "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) and extended metrics (SRMR, d_ULS, HTMT, HTMT2, Q², MGA) powering OpenPLS."
 readme = "README.md"
 license = { text = "GPL-3.0-or-later" }
 requires-python = ">=3.10"

openpls_engine-1.3.0/tests/test_higher_order.py

@@ -0,0 +1,355 @@
+#!/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.
+
+import numpy as np
+import pandas as pd
+import pytest
+
+import openpls.config as c
+from openpls.config import MV
+from openpls.higher_order import HigherOrder
+from openpls.mode import Mode
+from openpls.plspm import Plspm
+from openpls.scheme import Scheme
+
+
+def _hoc_dataset(
+    n: int = 600,
+    loading: float = 0.8,
+    hoc_to_y: float = 0.6,
+    seed: int = 0,
+) -> pd.DataFrame:
+    """Generate a 3-first-order + 1-target dataset.
+
+    The three first-order factors share a common HOC eta_h. The target
+    Y is driven by eta_h directly. With ``loading`` close to 1 the
+    first-order LVs are excellent reflectors of eta_h and the HOC path
+    to Y must approach ``hoc_to_y``.
+    """
+    rng = np.random.default_rng(seed)
+    eta_h = rng.standard_normal(n)
+    eta_y = hoc_to_y * eta_h + rng.standard_normal(n) * np.sqrt(1 - hoc_to_y ** 2)
+
+    def block(prefix: str, p: int, factor: np.ndarray) -> pd.DataFrame:
+        err = rng.standard_normal((n, p)) * np.sqrt(1 - loading ** 2)
+        arr = loading * factor[:, None] + err
+        return pd.DataFrame(arr, columns=[f"{prefix}{i+1}" for i in range(p)])
+
+    # First-order LVs all reflect eta_h with small idiosyncratic shifts so
+    # they are clearly distinct constructs but driven by the same higher
+    # factor (the canonical HOC setup).
+    eta1 = eta_h + 0.2 * rng.standard_normal(n)
+    eta2 = eta_h + 0.2 * rng.standard_normal(n)
+    eta3 = eta_h + 0.2 * rng.standard_normal(n)
+    df = pd.concat(
+        [
+            block("x1_", 4, eta1),
+            block("x2_", 4, eta2),
+            block("x3_", 4, eta3),
+            block("y", 3, eta_y),
+        ],
+        axis=1,
+    )
+    return df
+
+
+def _stage1_config(df: pd.DataFrame, first_order_mode: Mode = Mode.A) -> c.Config:
+    structure = c.Structure()
+    structure.add_path(["X1"], ["Y"])
+    structure.add_path(["X2"], ["Y"])
+    structure.add_path(["X3"], ["Y"])
+    config = c.Config(structure.path(), scaled=False)
+    config.add_lv_with_columns_named("X1", first_order_mode, df, "x1_")
+    config.add_lv_with_columns_named("X2", first_order_mode, df, "x2_")
+    config.add_lv_with_columns_named("X3", first_order_mode, df, "x3_")
+    config.add_lv_with_columns_named("Y", Mode.A, df, "y")
+    return config
+
+
+def _stage2_structure() -> c.Structure:
+    structure = c.Structure()
+    structure.add_path(["HOC"], ["Y"])
+    return structure
+
+
+def test_higher_order_type_i_reflective_reflective():
+    df = _hoc_dataset(seed=1)
+    base = Plspm(df, _stage1_config(df, Mode.A), Scheme.CENTROID)
+    hoc = base.higher_order(
+        name="HOC",
+        first_order=["X1", "X2", "X3"],
+        mode=Mode.A,
+        structure=_stage2_structure(),
+    )
+    # HOC loadings on its first-order indicators should all be strong
+    # and positive: a Type-I HOC where the first-order LVs are excellent
+    # reflectors of the same higher factor.
+    loadings = hoc.loadings()
+    assert (loadings > 0.7).all()
+    # HOC path to Y should be in the right direction and substantial.
+    paths = hoc.path_coefficients()
+    assert paths.loc["Y", "HOC"] > 0.3
+
+
+def test_higher_order_type_ii_reflective_formative():
+    df = _hoc_dataset(seed=2)
+    base = Plspm(df, _stage1_config(df, Mode.A), Scheme.CENTROID)
+    hoc = base.higher_order(
+        name="HOC",
+        first_order=["X1", "X2", "X3"],
+        mode=Mode.B,
+        structure=_stage2_structure(),
+    )
+    assert hoc.hoc_mode() == Mode.B
+    # Mode B HOC: formative weights, not loadings. summary() reports them.
+    summary = hoc.summary()
+    assert "weight" in summary.columns
+    assert (summary["weight"] > 0).all()
+
+
+def test_higher_order_type_iii_formative_reflective():
+    df = _hoc_dataset(seed=3)
+    base = Plspm(df, _stage1_config(df, Mode.B), Scheme.CENTROID)
+    hoc = base.higher_order(
+        name="HOC",
+        first_order=["X1", "X2", "X3"],
+        mode=Mode.A,
+        structure=_stage2_structure(),
+    )
+    loadings = hoc.loadings()
+    # First-order LVs are formative composites of the HOC indicators —
+    # they should still show consistent direction onto the HOC.
+    assert (loadings > 0).all()
+
+
+def test_higher_order_type_iv_formative_formative():
+    df = _hoc_dataset(seed=4)
+    base = Plspm(df, _stage1_config(df, Mode.B), Scheme.CENTROID)
+    hoc = base.higher_order(
+        name="HOC",
+        first_order=["X1", "X2", "X3"],
+        mode=Mode.B,
+        structure=_stage2_structure(),
+    )
+    summary = hoc.summary()
+    assert "weight" in summary.columns
+
+
+def test_higher_order_stage2_has_hoc_and_drops_first_order():
+    df = _hoc_dataset(seed=5)
+    base = Plspm(df, _stage1_config(df), Scheme.CENTROID)
+    hoc = base.higher_order(
+        name="HOC",
+        first_order=["X1", "X2", "X3"],
+        mode=Mode.A,
+        structure=_stage2_structure(),
+    )
+    refit = hoc.refit()
+    lvs = list(refit.path_coefficients().index)
+    assert "HOC" in lvs
+    assert "Y" in lvs
+    for old in ["X1", "X2", "X3"]:
+        assert old not in lvs
+
+
+def test_higher_order_recovers_hoc_path_close_to_truth():
+    """With strong loadings and a known underlying eta_h → Y coefficient,
+    the disjoint two-stage HOC path estimate should land near the truth."""
+    truth = 0.7
+    df = _hoc_dataset(n=1500, loading=0.9, hoc_to_y=truth, seed=42)
+    base = Plspm(df, _stage1_config(df), Scheme.CENTROID)
+    hoc = base.higher_order(
+        name="HOC",
+        first_order=["X1", "X2", "X3"],
+        mode=Mode.A,
+        structure=_stage2_structure(),
+    )
+    estimate = float(hoc.path_coefficients().loc["Y", "HOC"])
+    assert abs(estimate - truth) < 0.05
+
+
+def test_higher_order_rejects_duplicate_first_order():
+    df = _hoc_dataset()
+    base = Plspm(df, _stage1_config(df), Scheme.CENTROID)
+    with pytest.raises(ValueError):
+        base.higher_order(
+            name="HOC",
+            first_order=["X1", "X1"],
+            mode=Mode.A,
+            structure=_stage2_structure(),
+        )
+
+
+def test_higher_order_rejects_unknown_first_order():
+    df = _hoc_dataset()
+    base = Plspm(df, _stage1_config(df), Scheme.CENTROID)
+    with pytest.raises(ValueError):
+        base.higher_order(
+            name="HOC",
+            first_order=["X1", "NOT_IN_MODEL"],
+            mode=Mode.A,
+            structure=_stage2_structure(),
+        )
+
+
+def test_higher_order_rejects_name_collision():
+    df = _hoc_dataset()
+    base = Plspm(df, _stage1_config(df), Scheme.CENTROID)
+    with pytest.raises(ValueError):
+        base.higher_order(
+            name="X1",  # already an LV
+            first_order=["X1", "X2", "X3"],
+            mode=Mode.A,
+            structure=_stage2_structure(),
+        )
+
+
+def test_higher_order_rejects_first_order_in_stage2_structure():
+    df = _hoc_dataset()
+    base = Plspm(df, _stage1_config(df), Scheme.CENTROID)
+    bad = c.Structure()
+    bad.add_path(["HOC"], ["Y"])
+    bad.add_path(["X1"], ["Y"])  # first-order LV in stage-2 — must reject
+    with pytest.raises(ValueError):
+        base.higher_order(
+            name="HOC",
+            first_order=["X1", "X2", "X3"],
+            mode=Mode.A,
+            structure=bad,
+        )
+
+
+def test_higher_order_rejects_unknown_stage2_lv():
+    df = _hoc_dataset()
+    base = Plspm(df, _stage1_config(df), Scheme.CENTROID)
+    bad = c.Structure()
+    bad.add_path(["HOC"], ["NEW_LV"])  # not in base config
+    with pytest.raises(ValueError):
+        base.higher_order(
+            name="HOC",
+            first_order=["X1", "X2", "X3"],
+            mode=Mode.A,
+            structure=bad,
+        )
+
+
+def test_higher_order_requires_hoc_in_structure():
+    df = _hoc_dataset()
+    base = Plspm(df, _stage1_config(df), Scheme.CENTROID)
+    bad = c.Structure()
+    bad.add_path(["Y"], ["X2"])  # any path that does not mention HOC
+    with pytest.raises(ValueError):
+        base.higher_order(
+            name="HOC",
+            first_order=["X1", "X2", "X3"],
+            mode=Mode.A,
+            structure=bad,
+        )
+
+
+def test_higher_order_requires_two_first_order():
+    df = _hoc_dataset()
+    base = Plspm(df, _stage1_config(df), Scheme.CENTROID)
+    with pytest.raises(ValueError):
+        base.higher_order(
+            name="HOC",
+            first_order=["X1"],
+            mode=Mode.A,
+            structure=_stage2_structure(),
+        )
+
+
+def test_higher_order_base_and_refit_are_distinct_fits():
+    df = _hoc_dataset()
+    base = Plspm(df, _stage1_config(df), Scheme.CENTROID)
+    hoc = base.higher_order(
+        name="HOC",
+        first_order=["X1", "X2", "X3"],
+        mode=Mode.A,
+        structure=_stage2_structure(),
+    )
+    assert hoc.base() is base
+    assert hoc.refit() is not base
+
+
+def test_higher_order_indicator_columns_use_namespaced_names():
+    df = _hoc_dataset()
+    base = Plspm(df, _stage1_config(df), Scheme.CENTROID)
+    hoc = base.higher_order(
+        name="HOC",
+        first_order=["X1", "X2", "X3"],
+        mode=Mode.A,
+        structure=_stage2_structure(),
+    )
+    cols = hoc.indicator_columns()
+    assert cols == {"X1": "HOC__X1", "X2": "HOC__X2", "X3": "HOC__X3"}
+
+
+def test_higher_order_summary_shape_and_columns_mode_a():
+    df = _hoc_dataset()
+    base = Plspm(df, _stage1_config(df), Scheme.CENTROID)
+    hoc = base.higher_order(
+        name="HOC",
+        first_order=["X1", "X2", "X3"],
+        mode=Mode.A,
+        structure=_stage2_structure(),
+    )
+    summary = hoc.summary()
+    assert list(summary.columns) == ["first_order", "loading", "stage1_r_squared"]
+    assert list(summary["first_order"]) == ["X1", "X2", "X3"]
+    # X1/X2/X3 are exogenous in stage 1 → R² reported as 0 by inner_summary.
+    assert (summary["stage1_r_squared"] == 0.0).all()
+
+
+def test_higher_order_can_chain_nested_hoc():
+    """Calling higher_order on the stage-2 refit should chain — a HOC
+    can in turn become a first-order of a third-order construct."""
+    # Build a model with two sibling HOCs both pointing at Y.
+    df = _hoc_dataset(seed=11)
+    # Add a fourth first-order block so we can group (X1,X2) into HOC_A
+    # and (X3,X4) into HOC_B.
+    rng = np.random.default_rng(13)
+    eta = df["x1_1"] * 0.6 + rng.standard_normal(len(df)) * 0.4
+    err = rng.standard_normal((len(df), 4)) * np.sqrt(1 - 0.7 ** 2)
+    block_4 = pd.DataFrame(
+        0.7 * eta.to_numpy()[:, None] + err,
+        columns=[f"x4_{i+1}" for i in range(4)],
+        index=df.index,
+    )
+    df2 = pd.concat([df, block_4], axis=1)
+    structure = c.Structure()
+    structure.add_path(["X1"], ["Y"])
+    structure.add_path(["X2"], ["Y"])
+    structure.add_path(["X3"], ["Y"])
+    structure.add_path(["X4"], ["Y"])
+    config = c.Config(structure.path(), scaled=False)
+    for lv in ["X1", "X2", "X3", "X4"]:
+        config.add_lv_with_columns_named(lv, Mode.A, df2, lv.lower() + "_")
+    config.add_lv_with_columns_named("Y", Mode.A, df2, "y")
+    base = Plspm(df2, config, Scheme.CENTROID)
+
+    # The disjoint API rolls one HOC at a time. We do HOC_A first into
+    # an intermediate stage 2 that still keeps X3 and X4 as siblings.
+    s2a = c.Structure()
+    s2a.add_path(["HOC_A"], ["Y"])
+    s2a.add_path(["X3"], ["Y"])
+    s2a.add_path(["X4"], ["Y"])
+    stage2 = base.higher_order(
+        name="HOC_A", first_order=["X1", "X2"], mode=Mode.A, structure=s2a
+    ).refit()
+    # Then a second HOC on top of the stage-2 fit.
+    s3 = c.Structure()
+    s3.add_path(["HOC_A"], ["Y"])
+    s3.add_path(["HOC_B"], ["Y"])
+    stage3 = stage2.higher_order(
+        name="HOC_B", first_order=["X3", "X4"], mode=Mode.A, structure=s3
+    )
+    paths = stage3.path_coefficients()
+    assert "HOC_A" in paths.index
+    assert "HOC_B" in paths.index