Switched to PLSKit backend

Author: pawlenartowicz

README.md

@@ -277,42 +277,42 @@ New proposed algorithm. PLS regression operates directly in the full embedding s
 
 ```python
 result = ssd.fit_pls(
-    n_components=1,       # or "auto" for CV-based selection
+    n_components=1,       # or "sequence" / "postselection" for K-selection
     p_method="auto",      # significance test (see below)
     verbose=False,
 )
 ```
 
 | Argument | Type | Default | Description |
 |----------|------|---------|-------------|
-| `n_components` | `int \| "auto"` | `1` | Number of PLS components. `"auto"` picks argmax CV R² over 10-fold CV |
-| `cv_folds` | `int` | `10` | CV folds for component selection |
-| `pca_preprocess` | `int \| str \| None` | `None` | Optional PCA preprocessing (e.g. `50` or `"var95"`) |
+| `n_components` | `int \| "sequence" \| "postselection"` | `1` | Number of PLS components. Pass a string to delegate K-selection to `plskit.pls1_find_k` |
+| `cv_folds` | `int` | `10` | CV folds for `selector="cv_q2"` under `"postselection"` |
+| `k_cap` | `int` | `5` | Maximum K considered when `n_components` is a string |
+| `selection_kwargs` | `dict \| None` | `None` | Forwarded to `plskit.pls1_find_k` (e.g. `test_method`, `selector`, `alpha`) |
 | `p_method` | `str \| None` | `"auto"` | Significance test method |
 | `n_perm` | `int` | `1000` | Permutation iterations |
 | `n_splits` | `int` | `50` | Split-half iterations |
-| `split_ratio` | `float` | `0.5` | Training fraction for split-based tests |
 | `random_state` | `int` | `2137` | Random seed |
 | `verbose` | `bool` | `False` | Print progress |
 
 **`p_method` options**:
 
 | Value | Description |
 |-------|-------------|
-| `"auto"` | `"split"` when `n_components=1`, `"perm"` otherwise |
-| `"perm"` | Permutation test on cross-validated R-squared |
-| `"split"` | Split-half test with overlap-corrected t-test |
-| `"split_cal"` | Permutation-calibrated split-half (exact FPR control, slower) |
+| `"auto"` | `"split_nb"` when `n_components=1`, `"raw_perm"` otherwise |
+| `"raw_perm"` | Permutation test on cross-validated R-squared |
+| `"split_nb"` | Split-half test with overlap-corrected t-test |
+| `"split_perm"` | Permutation-calibrated split-half (exact FPR control, slower) |
 | `None` | Skip significance testing (p-value = NaN) |
 
 ### Multi-component PLS (in development)
 
-When you expect more than one interpretable semantic axis related to the outcome, `fit_multipls()` fits `k` PLS components, rotates the W-subspace (`"varimax"`, `"promax"`, or `"raw"`), and returns a container of per-dim leaves — one per rotated axis plus a `"combined"` leaf for the (rotation-invariant) unrotated prediction β.
+When you expect more than one interpretable semantic axis related to the outcome, `fit_multipls()` fits `k` PLS components, rotates the W-subspace (`"varimax"` or `"raw"`), and returns a container of per-dim leaves — one per rotated axis plus a `"combined"` leaf for the (rotation-invariant) unrotated prediction β.
 
 ```python
 result = ssd.fit_multipls(
     n_components=2,       # required, no default
-    rotate="varimax",     # or "promax" / "raw"
+    rotate="varimax",     # or "raw"
     p_method="auto",
     verbose=False,
 )
@@ -327,9 +327,8 @@ result["combined"].words        # zoom into unrotated prediction β
 | Argument | Type | Default | Description |
 |----------|------|---------|-------------|
 | `n_components` | `int` | — (required) | Number of PLS components to extract |
-| `rotate` | `"raw" \| "varimax" \| "promax"` | `"varimax"` | Rotation applied to the W-subspace |
-| `kappa` | `int \| float` | `4` | Promax exaggeration exponent (ignored for other rotations) |
-| `pca_preprocess`, `p_method`, `n_perm`, `n_splits`, `split_ratio`, `random_state`, `verbose` | — | — | Same meaning and defaults as `fit_pls` |
+| `rotate` | `"raw" \| "varimax"` | `"varimax"` | Rotation applied to the W-subspace |
+| `p_method`, `n_perm`, `n_splits`, `random_state`, `verbose` | — | — | Same meaning and defaults as `fit_pls` |
 
 > **Status.** API is stable for research use but feature parity with `PLSResult` (per-leaf clusters, snippets, misdiagnosed docs, per-dim diagnostics) is still being rolled out. See [`examples/demo_multipls.py`](examples/demo_multipls.py) and [`docs/api_reference.md`](docs/api_reference.md#fit_multipls--rotated-multi-component-pls-in-development).
 
@@ -604,7 +603,7 @@ Methods:
 - `.misdiagnosed(k=20, side="both")` -> `list[dict]`
 - `.snippets(pre_docs, top_per_side=200)` -> `dict`
 - `.snippets_extreme(pre_docs, k=50, by="predicted")` -> `dict`
-- `.split_test(n_splits=50, method="split")` — mutates in place: overwrites `pvalue`, `p_method`, `split_mean_r` (PLSResult only). Returns `self`.
+- `.split_test(n_splits=50, method="split_nb")` — mutates in place: overwrites `pvalue`, `p_method`, `split_mean_r` (PLSResult only). Returns `self`.
 - `.plot_sweep(path=None)` — PCA-K sweep plot (PCAOLSResult only)
 
 ### `GroupResult`

docs/api_reference.md

@@ -208,22 +208,23 @@ Returns a `PCAOLSResult`. Significance is reported as the OLS F-test. Sweep diag
 result = ssd.fit_pls(*,
     n_components=1,
     cv_folds=10,
-    pca_preprocess=None,
+    k_cap=5,
+    selection_kwargs=None,
     p_method="auto",
-    n_perm=1000, n_splits=50, split_ratio=0.5,
+    n_perm=1000, n_splits=50,
     random_state=2137, verbose=False,
 )
 ```
 
 | Argument | Type | Default | Description |
 |---|---|---|---|
-| `n_components` | `int \| "auto"` | `1` | Number of PLS components. `"auto"` picks argmax mean CV R² over `cv_folds`-fold CV. |
-| `cv_folds` | `int` | `10` | CV folds for `"auto"` component selection. |
-| `pca_preprocess` | `int \| str \| None` | `None` | Pre-PLS PCA reduction. Int = component count; `"var95"` retains 95 % of variance. |
-| `p_method` | `str \| None` | `"auto"` | `"perm"`, `"split"`, `"split_cal"`, `"auto"` (= `"split"` for 1 component, `"perm"` otherwise), or `None` to skip. |
-| `n_perm` | `int` | `1000` | Permutations for `"perm"` / `"split_cal"`. |
-| `n_splits` | `int` | `50` | Splits for `"split"` / `"split_cal"`. |
-| `split_ratio` | `float` | `0.5` | Train fraction for split-based tests. |
+| `n_components` | `int \| "sequence" \| "postselection"` | `1` | Number of PLS components. Pass a string to delegate K-selection to `plskit.pls1_find_k`: `"sequence"` (sequential incremental tests) or `"postselection"` (split-based selection + calibrated certificate). |
+| `cv_folds` | `int` | `10` | CV folds for `selector="cv_q2"` under `n_components="postselection"`. Ignored otherwise. |
+| `k_cap` | `int` | `5` | Maximum K considered when `n_components` is a string (further capped at `n − 1` and `D`). |
+| `selection_kwargs` | `dict \| None` | `None` | Extra keyword arguments forwarded to `plskit.pls1_find_k` (e.g. `test_method`, `selector`, `alpha`). |
+| `p_method` | `str \| None` | `"auto"` | `"raw_perm"`, `"split_nb"`, `"split_perm"`, `"auto"` (= `"split_nb"` for 1 component, `"raw_perm"` otherwise), or `None` to skip. |
+| `n_perm` | `int` | `1000` | Permutations for `"raw_perm"` / `"split_perm"`. |
+| `n_splits` | `int` | `50` | Splits for `"split_nb"` / `"split_perm"`. |
 | `random_state` | `int` | `2137` | Seed. |
 | `verbose` | `bool` | `False` | Print progress. |
 
@@ -261,21 +262,18 @@ Fits `n_components` PLS dimensions, rotates the W-subspace for interpretability,
 ```python
 result = ssd.fit_multipls(*,
     n_components,                    # required — no default
-    rotate="varimax",                # "varimax" | "promax" | "raw"
-    kappa=4,                         # promax exaggeration exponent
-    pca_preprocess=None,
+    rotate="varimax",                # "varimax" | "raw"
     p_method="auto",
-    n_perm=1000, n_splits=50, split_ratio=0.5,
+    n_perm=1000, n_splits=50,
     random_state=2137, verbose=False,
 )
 ```
 
 | Argument | Type | Default | Description |
 |---|---|---|---|
 | `n_components` | `int` | — | Number of PLS components to rotate. Required. Raises if NIPALS deflation produces fewer (no silent truncation). |
-| `rotate` | `str` | `"varimax"` | `"varimax"` (orthogonal), `"promax"` (oblique, correlated factors), `"raw"` (no rotation — still reorders dims by `|corr(t_i, y)|` and sign-flips). |
-| `kappa` | `int \| float` | `4` | Promax exaggeration exponent. Ignored for other rotations. |
-| `pca_preprocess`, `p_method`, `n_perm`, `n_splits`, `split_ratio`, `random_state`, `verbose` | — | — | Same meaning and defaults as `fit_pls`. |
+| `rotate` | `str` | `"varimax"` | `"varimax"` (orthogonal) or `"raw"` (no rotation — still reorders dims by `|corr(t_i, y)|` and sign-flips). |
+| `p_method`, `n_perm`, `n_splits`, `random_state`, `verbose` | — | — | Same meaning and defaults as `fit_pls`. |
 
 Returns a `MultiPLSResult` with:
 
@@ -357,7 +355,7 @@ ols.plot_sweep("sweep.png")
 ols.report(top_words=10, clusters=50).save("report_ols.md")
 
 # Continuous fit — PLS on the same SSD
-pls = ssd.fit_pls(n_components="auto", p_method="split")
+pls = ssd.fit_pls(n_components="postselection", p_method="split_nb")
 pls.report(top_words=10, clusters=50).save("report_pls.md")
 
 # Group comparison

docs/architecture.md

@@ -40,11 +40,10 @@ ssdiff/
 ├── lang_config.py     — language → spaCy model mapping (23 languages)
 ├── py.typed           — PEP 561 marker
 ├── backends/
-│   ├── pls.py         — PLS1 NIPALS, CV selection, perm / split / split_cal tests
+│   ├── pls.py         — plskit orchestration: mpls_fit (PLS1 + W-rotation), run_signal_test (raw_perm / split_nb / split_perm)
 │   ├── pca_sweep.py   — PCA + OLS; joint interpretability/stability sweep
 │   ├── _sweep_math.py — sweep scoring primitives
-│   ├── group.py       — unified permutation test (omnibus + pairwise)
-│   └── multipls.py    — varimax / promax rotation of the PLS W-subspace (in development)
+│   └── group.py       — unified permutation test (omnibus + pairwise)
 ├── results/
 │   ├── __init__.py       — public result exports
 │   ├── core.py           — Result ABC, View / ScalarView / TestView, save()/to_* helpers, parameter-keyed cache
@@ -100,24 +99,25 @@ No fitting runs at construction — just doc-vector preparation.
 ssd.x (n × D), ssd.y (n)
         │
         ├─ standardize X  (columns, ddof=0)
-        ├─ optional PCA preprocess  (var95 or fixed k) → Z
-        ├─ optional auto-select n_components  (K-fold CV, argmax R²)
-        ├─ NIPALS PLS1:
+        ├─ optional K-selection (plskit.pls1_find_k):
+        │    "sequence"      → sequential incremental tests, K* = first k
+        │                      that fails to reject
+        │    "postselection" → split A picks K*, split B re-tests at K*
+        ├─ NIPALS PLS1 (plskit.pls1_fit):
         │    for each component:
         │      w = X'y / ‖X'y‖
         │      t = Xw           (score)
         │      p = X't / t't    (loading)
         │      q = y't / t't    (y-loading)
         │      deflate X and y
         ├─ β = W (P'W)⁻¹ Q
-        ├─ back-project through PCA preprocess (if any)  →  β in embedding space
         ├─ unscale: β / X_scale
         ├─ orient β: flip if corr(ŷ, y) < 0
-        └─ p-value (optional):
-             "perm"       → full permutation on CV-R²
-             "split"      → repeated train/test split, overlap-corrected t
-             "split_cal"  → split procedure on permuted y → exact null
-             "auto"       → "split" for n_components=1, "perm" otherwise
+        └─ p-value (optional, via plskit.pls1_signal_test):
+             "raw_perm"   → full permutation on CV-R²
+             "split_nb"   → repeated train/test split, overlap-corrected t
+             "split_perm" → split procedure on permuted y → exact null
+             "auto"       → "split_nb" for n_components=1, "raw_perm" otherwise
                                 │
                                 ▼
                           PLSResult
@@ -154,19 +154,18 @@ ssd.x (n × D), ssd.y (n)
 ssd.x (n × D), ssd.y (n), ssd.embeddings
         │
         ├─ standardize X and y (caller-side — mpls_fit expects standardised input)
-        ├─ project vocabulary into the same column space → E_target
-        ├─ optional PCA preprocess → Z, E_target reduced to PCA space
-        ├─ backends.multipls.mpls_fit(Xs, ys, n_components, rotate, E_target, kappa):
-        │    NIPALS PLS1 → W, P, Q  (raise if returned k < n_components)
+        ├─ project vocabulary lazily via callable target  L = ((E - X_mean) / X_scale) @ W
+        ├─ backends.pls.mpls_fit(Xs, ys, n_components, rotate, E_target):
+        │    plskit.pls1_fit → W, P, Q  (raise if returned k < n_components)
         │    β_combined = W(P'W)⁻¹Q                    ← unrotated, rotation-invariant
         │    L = E_target @ W                          ← full-vocab projection (rotation target)
-        │    rotate("varimax" | "promax" | "raw") → W_pre
+        │    plskit.rotate("varimax" | "raw") → W_pre
         │    recompute dim scores: T_pre[:, i] = Xs @ W_pre[:, i]
         │    reorder dims by |corr(T_pre_i, ys)| desc; sign-flip so corr > 0
-        │    → W_rot, T_rot, rotation_meta (R, order, signs, sweeps, phi, pattern, …)
-        ├─ shared model-level p-value: perm / split / split_cal (same backends as fit_pls)
+        │    → W_rot, T_rot, rotation_meta (R, order, signs, sweeps, V_converged)
+        ├─ shared model-level p-value: raw_perm / split_nb / split_perm (same helper as fit_pls)
         └─ wrap into MultiPLSResult with leaves:
-             "dim-1", …, "dim-k"  → β_i = W_rot[:, i]   (pattern column for promax)
+             "dim-1", …, "dim-k"  → β_i = W_rot[:, i]
              "combined"           → β   = β_combined    (unrotated prediction direction)
                 │
                 ▼
@@ -389,10 +388,10 @@ Analytic F-test from OLS in PCA space. Tests the null that all PCA-space regress
 
 | name | idea | cost | control |
 |---|---|---|---|
-| `"perm"` | shuffle y, refit PLS with CV, compare observed CV-R² to null | `n_perm` PLS refits | exact under permutation |
-| `"split"` | repeated train/test split, correlate predictions, overlap-corrected t | `n_splits` PLS fits | asymptotic |
-| `"split_cal"` | run the full split procedure on permuted y → exact null | `n_splits × n_perm` PLS fits | exact |
-| `"auto"` | `"split"` for `n_components=1`, `"perm"` otherwise | — | — |
+| `"raw_perm"` | shuffle y, refit PLS with CV, compare observed CV-R² to null | `n_perm` PLS refits | exact under permutation |
+| `"split_nb"` | repeated train/test split, correlate predictions, overlap-corrected t | `n_splits` PLS fits | asymptotic |
+| `"split_perm"` | run the full split procedure on permuted y → exact null | `n_splits × n_perm` PLS fits | exact |
+| `"auto"` | `"split_nb"` for `n_components=1`, `"raw_perm"` otherwise | — | — |
 
 All three are exposed as `result.test(name, **params)` for reruns; `result.stats.pvalue` is propagated by the `_on_rerun` hook.
 

docs/results.md

@@ -57,7 +57,7 @@ Every result exposes its data through **views** — small objects you can print,
 |---|---|---|
 | `View[T]` | Tabular. Iterates frozen dataclasses. | `result.words`, `result.docs` |
 | `ScalarView` | Single row. Field access via `.r2` or `["r2"]`. | `result.stats`, `result.fit_info` |
-| `TestView` | Callable ScalarView — calling it reruns the test. | `result.test("perm", n_perm=5000)` |
+| `TestView` | Callable ScalarView — calling it reruns the test. | `result.test("raw_perm", n_perm=5000)` |
 
 All views share the same output methods:
 
@@ -225,14 +225,14 @@ Leaf keys are `"dim-1"`, …, `"dim-k"`, `"combined"` (strings). `res.words` / `
 `res.test(...)` runs one whole-model test — CV-R² is a model-level quantity, rotation is free for prediction. Same three backends as `PLSResult`:
 
 ```python
-res.test("split",     n_splits=100)
-res.test("perm",      n_perm=2000)
-res.test("split_cal", n_splits=50, n_perm=2000)
+res.test("split_nb",   n_splits=100)
+res.test("raw_perm",   n_perm=2000)
+res.test("split_perm", n_splits=50, n_perm=2000)
 ```
 
 ### Rotation diagnostics
 
-`res.pls_info` exposes: `n_components`, `rotate`, `pca_k`, `order`, `signs`, `kaiser_normalized`, `sweeps`, `V_converged`, `kappa`, `pvalue_source`, `random_state`.
+`res.pls_info` exposes: `n_components`, `rotate`, `order`, `signs`, `kaiser_normalized`, `sweeps`, `V_converged`, `pvalue_source`, `random_state`.
 
 ### Minimal report (v1)
 
@@ -328,12 +328,12 @@ Unsupported extensions raise `ValueError` with the list of supported ones.
 
 **PLS:**
 ```python
-result.test("perm",      n_perm=5000, seed=0)
-result.test("split",     n_splits=100, split_ratio=0.5)
-result.test("split_cal", n_splits=50, n_perm=2000)
+result.test("raw_perm",   n_perm=5000, seed=0)
+result.test("split_nb",   n_splits=100)
+result.test("split_perm", n_splits=50, n_perm=2000)
 
 result.test.pvalue         # current p-value
-result.test.name           # "perm" | "split" | "split_cal"
+result.test.name           # "raw_perm" | "split_nb" | "split_perm"
 ```
 
 **Groups:**
@@ -474,7 +474,7 @@ Missing deps raise `ImportError` with an install hint.
 | Doc + raw text | `result.docs.id(42)` |
 | Recompute snippets | `result.snippets(top_per_side=200, min_cosine=0.4)` |
 | Snippets inside cluster 3 | `result.clusters.pos.snippets(cluster_id=3)` |
-| Rerun PLS test | `result.test("perm", n_perm=5000)` |
+| Rerun PLS test | `result.test("raw_perm", n_perm=5000)` |
 | Rerun group test | `gr.test(n_perm=10000, correction="fdr_bh")` |
 | Zoom to one pair | `gr[('g1','g2')]` |
 | Per-pair top words | `gr[('g1','g2')].words.pos(20)` |