factorlasso 0.2.2__tar.gz → 0.3.0__tar.gz

factorlasso-0.3.0/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.4
+Name: factorlasso
+Version: 0.3.0
+Summary: Sparse factor model estimation with sign-constrained LASSO, prior-centered regularisation, and hierarchical group LASSO (HCGL)
+Author-email: Artur Sepp <artursepp@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/ArturSepp/factorlasso
+Project-URL: Documentation, https://factorlasso.readthedocs.io
+Project-URL: Repository, https://github.com/ArturSepp/factorlasso
+Project-URL: Issues, https://github.com/ArturSepp/factorlasso/issues
+Project-URL: Changelog, https://github.com/ArturSepp/factorlasso/blob/main/CHANGELOG.md
+Keywords: lasso,group-lasso,factor-model,penalized-regression,sparse-regression,sign-constraints,covariance-estimation,cvxpy,multi-output-regression
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Requires-Dist: pandas>=1.4
+Requires-Dist: scipy>=1.9
+Requires-Dist: cvxpy>=1.3
+Requires-Dist: openpyxl>=3.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=6.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=1.0; extra == "docs"
+Requires-Dist: numpydoc>=1.5; extra == "docs"
+Dynamic: license-file
+
+# factorlasso
+
+**Sparse multi-output regression with sign constraints, prior-centered
+regularisation, and hierarchical group LASSO — via CVXPY.**
+
+[![PyPI](https://img.shields.io/pypi/v/factorlasso.svg)](https://pypi.org/project/factorlasso/)
+[![Python](https://img.shields.io/pypi/pyversions/factorlasso.svg)](https://pypi.org/project/factorlasso/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+`factorlasso` is a small, dependency-light Python package for fitting sparse
+multi-output linear models
+
+$$
+Y = X\beta^\top + \varepsilon,
+\qquad \beta \in \mathbb{R}^{N \times M}
+$$
+
+when three things matter:
+
+- Some coefficients **must be zero, non-negative, or non-positive**, possibly by
+  asset, by factor, or both.
+- You have a **prior** β₀ and want to penalise `‖β − β₀‖`, not `‖β‖`.
+- You want **structured sparsity** — groups of responses entering or leaving
+  the model together — where the groups are either user-supplied or discovered
+  by hierarchical clustering of the response correlation matrix (HCGL).
+
+It is written in pure numpy/pandas/scipy/cvxpy. No numba, no custom
+coordinate descent. The solver is CVXPY (default `CLARABEL`), so problem
+formulation is explicit and auditable.
+
+---
+
+## Installation
+
+```bash
+pip install factorlasso
+```
+
+Requires Python ≥ 3.9, CVXPY ≥ 1.3, and numpy / pandas / scipy / openpyxl.
+
+---
+
+## Quickstart
+
+```python
+import numpy as np
+import pandas as pd
+from factorlasso import LassoModel, LassoModelType
+
+rng = np.random.default_rng(0)
+T, M, N = 200, 4, 10
+X = pd.DataFrame(rng.standard_normal((T, M)), columns=[f"f{i}" for i in range(M)])
+Y = pd.DataFrame(rng.standard_normal((T, N)), columns=[f"y{i}" for i in range(N)])
+
+model = LassoModel(model_type=LassoModelType.LASSO, reg_lambda=1e-3).fit(x=X, y=Y)
+
+model.coef_         # (N, M) estimated β
+model.intercept_    # (N,) estimated α
+model.predict(X)    # Ŷ
+model.score(X, Y)   # mean R²
+```
+
+The API mirrors scikit-learn: `fit(x, y)`, `predict(x)`, `score(x, y)`,
+`get_params()`, `set_params()`. Fitted attributes carry a trailing underscore.
+
+---
+
+## What makes it different
+
+### 1. Per-element sign constraints
+
+A `(N × M)` matrix drives the constraints. Each entry is one of
+`{0, 1, -1, NaN}`: equality-to-zero, non-negative, non-positive, or free.
+This lets a single fit encode structural knowledge that spans multiple
+responses.
+
+```python
+signs = pd.DataFrame(np.nan, index=Y.columns, columns=X.columns)
+signs.loc["y0", "f0"] = 1      # β[y0, f0] ≥ 0
+signs.loc["y0", "f1"] = 0      # β[y0, f1] == 0
+signs.loc["y1", "f0"] = -1     # β[y1, f0] ≤ 0
+
+model = LassoModel(
+    reg_lambda=1e-3,
+    factors_beta_loading_signs=signs,
+).fit(x=X, y=Y)
+```
+
+Scikit-learn's `Lasso` supports only a single `positive` flag across the whole
+coefficient matrix. Arbitrary per-element sign constraints are not expressible
+without a custom CVXPY problem; this is that custom problem, packaged.
+
+### 2. Prior-centered regularisation
+
+Pass a `(N × M)` DataFrame `factors_beta_prior` to penalise `‖β − β₀‖` instead
+of `‖β‖`. The prior is a soft target, not a hard constraint — the penalty
+tension between data fit and prior is still controlled by `reg_lambda`.
+
+```python
+prior = 0.5 * np.sign(X.corrwith(Y["y0"]).to_numpy())
+# ... build an (N, M) DataFrame `prior_df` with that structure ...
+
+model = LassoModel(
+    reg_lambda=1e-3,
+    factors_beta_prior=prior_df,
+).fit(x=X, y=Y)
+```
+
+### 3. Hierarchical Clustering Group LASSO (HCGL)
+
+The groups in classical group LASSO are user-specified. HCGL discovers them
+from the data: EWMA correlation of the response matrix → Ward's linkage →
+dendrogram cut at `cutoff_fraction × max(pdist)` → block-sparse penalty on
+the resulting clusters.
+
+```python
+model = LassoModel(
+    model_type=LassoModelType.GROUP_LASSO_CLUSTERS,
+    reg_lambda=1e-4,
+    cutoff_fraction=0.5,   # tune granularity; smaller → tighter clusters
+    span=60,               # EWMA span for correlation estimate
+).fit(x=X, y=Y)
+
+model.coef_        # (N, M)
+model.clusters_    # pd.Series of cluster labels per response
+model.linkage_     # scipy linkage matrix
+```
+
+Useful when you suspect group structure in the responses but don't know the
+partition — or when the correct partition drifts over time, so any manual
+grouping would need to be refit anyway.
+
+---
+
+## When to use it — and when not
+
+**Use it when:**
+
+- Multi-output LASSO with heterogeneous sign constraints across the coefficient
+  matrix.
+- You have a prior `β₀` that should shrink the fit instead of zero.
+- You need discovered-group structured sparsity (HCGL).
+- You want a small, auditable CVXPY-based tool rather than a coordinate-descent
+  library with opaque internals.
+
+**Reach for something else when:**
+
+- Your problem is single-output elastic-net at large scale — `scikit-learn`,
+  `celer`, or `skglm` will be faster and have years of battle-testing.
+- You need fixed-group group LASSO at very large scale — `group-lasso` or
+  `asgl` are the standard tools.
+- You need non-linear models, random effects, or GLM link functions.
+
+A feature-by-feature comparison matrix is in
+[`COMPARISON.md`](COMPARISON.md).
+
+---
+
+## Examples
+
+Three runnable examples in [`examples/`](examples/):
+
+- [`genomics_factor_model.py`](examples/genomics_factor_model.py) —
+  QTL-style multi-response LASSO: genotype matrix → expression panel, with
+  sign constraints derived from biological priors.
+- [`finance_factor_model.py`](examples/finance_factor_model.py) —
+  Multi-asset factor decomposition with sign constraints and HCGL clustering.
+- [`cv_lambda_selection.py`](examples/cv_lambda_selection.py) —
+  Time-series cross-validated `reg_lambda` selection via `LassoModelCV` with
+  expanding-window splits.
+
+---
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+The suite currently has 201 tests at 98%+ coverage, including numerical parity
+tests against `qis` for the EWMA primitives and against `scikit-learn` for the
+LASSO path.
+
+---
+
+## Citation
+
+If you use `factorlasso` in academic work, please cite:
+
+```bibtex
+@article{SeppOssaKastenholz2026,
+  author  = {Sepp, Artur and Ossa, Ivan and Kastenholz, Mika},
+  title   = {Robust Optimization of Strategic and Tactical Asset Allocation
+             for Multi-Asset Portfolios},
+  journal = {The Journal of Portfolio Management},
+  year    = {2026},
+  volume  = {52},
+  number  = {4},
+  pages   = {86--120},
+}
+
+@software{factorlasso,
+  author  = {Sepp, Artur},
+  title   = {factorlasso: Sparse Factor Model Estimation with Constrained LASSO
+             in Python},
+  year    = {2026},
+  url     = {https://github.com/ArturSepp/factorlasso},
+}
+```
+
+---
+
+## Contributing & feedback
+
+Issues and pull requests welcome at
+<https://github.com/ArturSepp/factorlasso>.
+
+See [`CHANGELOG.md`](CHANGELOG.md) for release history.
+
+---
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

factorlasso-0.3.0/README.md

@@ -0,0 +1,225 @@
+# factorlasso
+
+**Sparse multi-output regression with sign constraints, prior-centered
+regularisation, and hierarchical group LASSO — via CVXPY.**
+
+[![PyPI](https://img.shields.io/pypi/v/factorlasso.svg)](https://pypi.org/project/factorlasso/)
+[![Python](https://img.shields.io/pypi/pyversions/factorlasso.svg)](https://pypi.org/project/factorlasso/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+`factorlasso` is a small, dependency-light Python package for fitting sparse
+multi-output linear models
+
+$$
+Y = X\beta^\top + \varepsilon,
+\qquad \beta \in \mathbb{R}^{N \times M}
+$$
+
+when three things matter:
+
+- Some coefficients **must be zero, non-negative, or non-positive**, possibly by
+  asset, by factor, or both.
+- You have a **prior** β₀ and want to penalise `‖β − β₀‖`, not `‖β‖`.
+- You want **structured sparsity** — groups of responses entering or leaving
+  the model together — where the groups are either user-supplied or discovered
+  by hierarchical clustering of the response correlation matrix (HCGL).
+
+It is written in pure numpy/pandas/scipy/cvxpy. No numba, no custom
+coordinate descent. The solver is CVXPY (default `CLARABEL`), so problem
+formulation is explicit and auditable.
+
+---
+
+## Installation
+
+```bash
+pip install factorlasso
+```
+
+Requires Python ≥ 3.9, CVXPY ≥ 1.3, and numpy / pandas / scipy / openpyxl.
+
+---
+
+## Quickstart
+
+```python
+import numpy as np
+import pandas as pd
+from factorlasso import LassoModel, LassoModelType
+
+rng = np.random.default_rng(0)
+T, M, N = 200, 4, 10
+X = pd.DataFrame(rng.standard_normal((T, M)), columns=[f"f{i}" for i in range(M)])
+Y = pd.DataFrame(rng.standard_normal((T, N)), columns=[f"y{i}" for i in range(N)])
+
+model = LassoModel(model_type=LassoModelType.LASSO, reg_lambda=1e-3).fit(x=X, y=Y)
+
+model.coef_         # (N, M) estimated β
+model.intercept_    # (N,) estimated α
+model.predict(X)    # Ŷ
+model.score(X, Y)   # mean R²
+```
+
+The API mirrors scikit-learn: `fit(x, y)`, `predict(x)`, `score(x, y)`,
+`get_params()`, `set_params()`. Fitted attributes carry a trailing underscore.
+
+---
+
+## What makes it different
+
+### 1. Per-element sign constraints
+
+A `(N × M)` matrix drives the constraints. Each entry is one of
+`{0, 1, -1, NaN}`: equality-to-zero, non-negative, non-positive, or free.
+This lets a single fit encode structural knowledge that spans multiple
+responses.
+
+```python
+signs = pd.DataFrame(np.nan, index=Y.columns, columns=X.columns)
+signs.loc["y0", "f0"] = 1      # β[y0, f0] ≥ 0
+signs.loc["y0", "f1"] = 0      # β[y0, f1] == 0
+signs.loc["y1", "f0"] = -1     # β[y1, f0] ≤ 0
+
+model = LassoModel(
+    reg_lambda=1e-3,
+    factors_beta_loading_signs=signs,
+).fit(x=X, y=Y)
+```
+
+Scikit-learn's `Lasso` supports only a single `positive` flag across the whole
+coefficient matrix. Arbitrary per-element sign constraints are not expressible
+without a custom CVXPY problem; this is that custom problem, packaged.
+
+### 2. Prior-centered regularisation
+
+Pass a `(N × M)` DataFrame `factors_beta_prior` to penalise `‖β − β₀‖` instead
+of `‖β‖`. The prior is a soft target, not a hard constraint — the penalty
+tension between data fit and prior is still controlled by `reg_lambda`.
+
+```python
+prior = 0.5 * np.sign(X.corrwith(Y["y0"]).to_numpy())
+# ... build an (N, M) DataFrame `prior_df` with that structure ...
+
+model = LassoModel(
+    reg_lambda=1e-3,
+    factors_beta_prior=prior_df,
+).fit(x=X, y=Y)
+```
+
+### 3. Hierarchical Clustering Group LASSO (HCGL)
+
+The groups in classical group LASSO are user-specified. HCGL discovers them
+from the data: EWMA correlation of the response matrix → Ward's linkage →
+dendrogram cut at `cutoff_fraction × max(pdist)` → block-sparse penalty on
+the resulting clusters.
+
+```python
+model = LassoModel(
+    model_type=LassoModelType.GROUP_LASSO_CLUSTERS,
+    reg_lambda=1e-4,
+    cutoff_fraction=0.5,   # tune granularity; smaller → tighter clusters
+    span=60,               # EWMA span for correlation estimate
+).fit(x=X, y=Y)
+
+model.coef_        # (N, M)
+model.clusters_    # pd.Series of cluster labels per response
+model.linkage_     # scipy linkage matrix
+```
+
+Useful when you suspect group structure in the responses but don't know the
+partition — or when the correct partition drifts over time, so any manual
+grouping would need to be refit anyway.
+
+---
+
+## When to use it — and when not
+
+**Use it when:**
+
+- Multi-output LASSO with heterogeneous sign constraints across the coefficient
+  matrix.
+- You have a prior `β₀` that should shrink the fit instead of zero.
+- You need discovered-group structured sparsity (HCGL).
+- You want a small, auditable CVXPY-based tool rather than a coordinate-descent
+  library with opaque internals.
+
+**Reach for something else when:**
+
+- Your problem is single-output elastic-net at large scale — `scikit-learn`,
+  `celer`, or `skglm` will be faster and have years of battle-testing.
+- You need fixed-group group LASSO at very large scale — `group-lasso` or
+  `asgl` are the standard tools.
+- You need non-linear models, random effects, or GLM link functions.
+
+A feature-by-feature comparison matrix is in
+[`COMPARISON.md`](COMPARISON.md).
+
+---
+
+## Examples
+
+Three runnable examples in [`examples/`](examples/):
+
+- [`genomics_factor_model.py`](examples/genomics_factor_model.py) —
+  QTL-style multi-response LASSO: genotype matrix → expression panel, with
+  sign constraints derived from biological priors.
+- [`finance_factor_model.py`](examples/finance_factor_model.py) —
+  Multi-asset factor decomposition with sign constraints and HCGL clustering.
+- [`cv_lambda_selection.py`](examples/cv_lambda_selection.py) —
+  Time-series cross-validated `reg_lambda` selection via `LassoModelCV` with
+  expanding-window splits.
+
+---
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+The suite currently has 201 tests at 98%+ coverage, including numerical parity
+tests against `qis` for the EWMA primitives and against `scikit-learn` for the
+LASSO path.
+
+---
+
+## Citation
+
+If you use `factorlasso` in academic work, please cite:
+
+```bibtex
+@article{SeppOssaKastenholz2026,
+  author  = {Sepp, Artur and Ossa, Ivan and Kastenholz, Mika},
+  title   = {Robust Optimization of Strategic and Tactical Asset Allocation
+             for Multi-Asset Portfolios},
+  journal = {The Journal of Portfolio Management},
+  year    = {2026},
+  volume  = {52},
+  number  = {4},
+  pages   = {86--120},
+}
+
+@software{factorlasso,
+  author  = {Sepp, Artur},
+  title   = {factorlasso: Sparse Factor Model Estimation with Constrained LASSO
+             in Python},
+  year    = {2026},
+  url     = {https://github.com/ArturSepp/factorlasso},
+}
+```
+
+---
+
+## Contributing & feedback
+
+Issues and pull requests welcome at
+<https://github.com/ArturSepp/factorlasso>.
+
+See [`CHANGELOG.md`](CHANGELOG.md) for release history.
+
+---
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

{factorlasso-0.2.2 → factorlasso-0.3.0}/factorlasso/cluster_utils.py

@@ -46,21 +46,36 @@ import scipy.cluster.hierarchy as spc
 # Clustering from correlation
 # ═══════════════════════════════════════════════════════════════════════
 
+# Default fraction of ``max(pdist)`` at which to cut the dendrogram.
+# 0.5 is the package-wide convention — half the maximum pairwise
+# correlation-distance — and empirically produces ~15–25 clusters on
+# a 150-asset multi-asset universe.  Callers that need a different
+# granularity can override via ``cutoff_fraction``.
+DEFAULT_CUTOFF_FRACTION: float = 0.5
+
 
 def compute_clusters_from_corr_matrix(
     corr_matrix: pd.DataFrame,
+    cutoff_fraction: float = DEFAULT_CUTOFF_FRACTION,
 ) -> Tuple[pd.Series, np.ndarray, float]:
     """
     Hierarchical clustering from a correlation matrix (Ward's method).
 
     Converts correlation to distance ``(1 − corr)``, applies Ward's
-    agglomerative clustering, and cuts the dendrogram at 50 % of the
-    maximum pairwise distance.
+    agglomerative clustering, and cuts the dendrogram at
+    ``cutoff_fraction × max(pairwise distance)``.
 
     Parameters
     ----------
     corr_matrix : pd.DataFrame, shape (N, N)
         Square correlation matrix.
+    cutoff_fraction : float, default 0.5
+        Fraction of ``max(pdist)`` at which to cut the dendrogram.
+        Must lie in ``(0, 1]``.  Smaller values produce more, tighter
+        clusters; larger values produce fewer, looser clusters.  The
+        default ``0.5`` is the canonical setting used throughout the
+        MATF-CMA pipeline and typically yields ~15–25 clusters on a
+        150-asset multi-asset universe.
 
     Returns
     -------
@@ -69,7 +84,8 @@ def compute_clusters_from_corr_matrix(
     linkage : np.ndarray
         Scipy linkage matrix.
     cutoff : float
-        Distance threshold used for cutting.
+        Absolute distance threshold used for cutting
+        (``cutoff_fraction × max(pdist)``).
 
     Notes
     -----
@@ -81,7 +97,24 @@ def compute_clusters_from_corr_matrix(
     and computed Euclidean distances between those rows — a different
     (non-semantic) metric that conflated correlation structure with
     higher-order geometric relationships.
+
+    Examples
+    --------
+    >>> import numpy as np, pandas as pd
+    >>> from factorlasso import compute_clusters_from_corr_matrix
+    >>> rng = np.random.default_rng(0)
+    >>> X = rng.standard_normal((200, 6))
+    >>> X[:, 1] = X[:, 0] + 0.1 * rng.standard_normal(200)  # 0 & 1 correlated
+    >>> C = pd.DataFrame(np.corrcoef(X, rowvar=False),
+    ...                  columns=list("abcdef"), index=list("abcdef"))
+    >>> clusters, _, cutoff = compute_clusters_from_corr_matrix(C)
+    >>> clusters.loc['a'] == clusters.loc['b']
+    True
     """
+    if not (0.0 < cutoff_fraction <= 1.0):
+        raise ValueError(
+            f"cutoff_fraction must lie in (0, 1], got {cutoff_fraction!r}"
+        )
     corr_matrix = corr_matrix.fillna(0.0)
     # squareform(1 - C) is the correct conversion from a correlation matrix
     # to scipy's condensed pairwise-distance vector. Clip guards against
@@ -91,7 +124,7 @@ def compute_clusters_from_corr_matrix(
     np.fill_diagonal(dist_square, 0.0)
     pdist = spc.distance.squareform(dist_square, checks=False)
     linkage = spc.linkage(pdist, method='ward')
-    cutoff = 0.5 * np.max(pdist)
+    cutoff = cutoff_fraction * np.max(pdist)
     idx = spc.fcluster(linkage, cutoff, 'distance')
     clusters = pd.Series(idx, index=corr_matrix.columns)
     return clusters, linkage, cutoff

{factorlasso-0.2.2 → factorlasso-0.3.0}/factorlasso/cv.py

@@ -31,14 +31,28 @@ True
 
 from __future__ import annotations
 
+import sys
+import warnings
 from dataclasses import dataclass, field
 from typing import Iterator, Optional, Sequence, Tuple
 
+import cvxpy as cvx
 import numpy as np
 import pandas as pd
 
 from factorlasso.lasso_estimator import LassoModel
 
+# Errors we treat as "this fold failed, record NaN and continue".
+# Anything else (KeyboardInterrupt, MemoryError, attribute errors from
+# bad user kwargs) should propagate to the caller.
+_FOLD_ERRORS: Tuple[type, ...] = (
+    cvx.error.SolverError,
+    cvx.error.DCPError,
+    ValueError,
+    np.linalg.LinAlgError,
+)
+
+
 # ═══════════════════════════════════════════════════════════════════════
 # Time-series splits
 # ═══════════════════════════════════════════════════════════════════════
@@ -134,6 +148,13 @@ class LassoModelCV:
     -----
     Scoring uses :meth:`LassoModel.score`, which is mean R² across
     response variables.  Higher is better.
+
+    Fold failures in the solver (``cvx.error.SolverError``,
+    ``LinAlgError``, ``ValueError``, ``cvx.error.DCPError``) are caught
+    and recorded as NaN in ``cv_scores_``.  Any other exception —
+    ``KeyboardInterrupt``, ``MemoryError``, ``AttributeError`` from
+    an unexpected kwarg — propagates so that real bugs are not silently
+    swallowed by the CV loop.
     """
 
     lambdas: Optional[Sequence[float]] = None
@@ -165,7 +186,8 @@ class LassoModelCV:
         y : pd.DataFrame, shape (T, N)
             Response (asset) returns.  May contain NaNs.
         verbose : bool, default False
-            Forwarded to :meth:`LassoModel.fit`.
+            If True, forwarded to :meth:`LassoModel.fit` and a warning
+            is emitted for every fold that fails.
 
         Returns
         -------
@@ -196,9 +218,21 @@ class LassoModelCV:
                         x=x.iloc[tr], y=y.iloc[tr], verbose=verbose,
                     )
                     scores[i, j] = model.score(x.iloc[te], y.iloc[te])
-                except Exception:
-                    # Solver failure or degenerate fold — leave NaN
-                    pass
+                except _FOLD_ERRORS as err:
+                    if verbose:
+                        warnings.warn(
+                            f"CV fold (lambda={lam:.2e}, split={j}) failed: "
+                            f"{type(err).__name__}: {err}",
+                            RuntimeWarning,
+                            stacklevel=2,
+                        )
+                        print(
+                            f"[LassoModelCV] fold failed "
+                            f"(lambda={lam:.2e}, split={j}): "
+                            f"{type(err).__name__}: {err}",
+                            file=sys.stderr,
+                        )
+                    # Fall through with NaN score
 
         cv_scores = pd.DataFrame(
             scores,