factorlasso 0.3.2__tar.gz → 0.3.4__tar.gz

{factorlasso-0.3.2 → factorlasso-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: factorlasso
-Version: 0.3.2
+Version: 0.3.4
 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
@@ -45,7 +45,7 @@ Dynamic: license-file
 # factorlasso
 
 **Sparse multi-output regression with sign constraints, prior-centered
-regularisation, and hierarchical group LASSO — via CVXPY.**
+regularisation, hierarchical group LASSO, and sparse 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/)
@@ -59,7 +59,7 @@ Y = X\beta^\top + \varepsilon,
 \qquad \beta \in \mathbb{R}^{N \times M}
 $$
 
-when three things matter:
+when four things matter:
 
 - Some coefficients **must be zero, non-negative, or non-positive**, possibly by
   asset, by factor, or both.
@@ -67,6 +67,9 @@ when three things matter:
 - 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).
+- You want to combine **group-level selection with within-group elementwise
+  sparsity** via a tunable mix of group L2 and L1 penalties (Sparse Group
+  LASSO).
 
 It is written in pure numpy/pandas/scipy/cvxpy. No numba, no custom
 coordinate descent. The solver is CVXPY (default `CLARABEL`), so problem
@@ -174,6 +177,49 @@ 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.
 
+### 4. Sparse Group LASSO
+
+Group LASSO selects whole groups in or out — every response inside an
+"active" group gets a non-zero loading. When the discovered groups are
+slightly heterogeneous (and HCGL clusters often are, especially at coarser
+`cutoff_fraction`), this admits noisy within-group loadings on responses
+that don't actually load on the factor.
+
+The `l1_weight` mixing parameter α ∈ [0, 1] adds an elementwise L1 penalty
+on top of the group L2 (Simon, Friedman, Hastie & Tibshirani 2013):
+
+$$
+\mathcal{P}(\beta) = (1 - \alpha)\,\lambda \sum_g w_g \, \|\beta_g - \beta_0\|_{2,1}
+\;+\; \alpha\,\lambda \, \|\beta - \beta_0\|_1
+$$
+
+```python
+model = LassoModel(
+    model_type=LassoModelType.GROUP_LASSO_CLUSTERS,
+    reg_lambda=1e-4,
+    cutoff_fraction=0.65,   # coarser clusters
+    l1_weight=0.10,         # α — group L2 still primary, L1 corrects within-group
+).fit(x=X, y=Y)
+```
+
+The interpretation is "group-then-prune": the group L2 term still drives
+group-level selection, while the L1 term zeros individual asset-factor
+coefficients within active groups whose contribution is noise. Setting
+`l1_weight=0.0` (the default) reduces exactly to pure group LASSO and is
+backward-compatible — the L1 term is dropped from the CVX problem entirely
+when α = 0, with zero runtime cost.
+
+Typical research range: α ∈ [0.05, 0.20]. Above ~0.30 the group structure
+stops driving the model and the result reverts toward plain LASSO. The
+penalty is centered on the same prior `β₀` as the group term, so the two
+shrinkage mechanisms compose consistently.
+
+The L1 term respects the same per-element sign constraints and the same
+prior as the group term, so all four features in this section compose: a
+single fit can simultaneously enforce sign constraints, shrink toward a
+prior, group-select via HCGL clusters, and apply within-group elementwise
+sparsity.
+
 ---
 
 ## When to use it — and when not
@@ -184,6 +230,8 @@ grouping would need to be refit anyway.
   matrix.
 - You have a prior `β₀` that should shrink the fit instead of zero.
 - You need discovered-group structured sparsity (HCGL).
+- You need group-level selection with within-group elementwise sparsity
+  (sparse group LASSO at small-to-moderate α).
 - You want a small, auditable CVXPY-based tool rather than a coordinate-descent
   library with opaque internals.
 
@@ -193,6 +241,11 @@ grouping would need to be refit anyway.
   `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 sparse group LASSO at large α (close to 1.0) or at very large
+  scale — specialised solvers like `asgl` or `SGL` handle proximal-operator
+  acceleration that the CVXPY formulation here does not. This package's
+  sparse group LASSO is intended for moderate α ∈ [0, 0.3] where the group
+  structure remains primary.
 - You need non-linear models, random effects, or GLM link functions.
 
 A feature-by-feature comparison matrix is in

{factorlasso-0.3.2 → factorlasso-0.3.4}/README.md

@@ -1,7 +1,7 @@
 # factorlasso
 
 **Sparse multi-output regression with sign constraints, prior-centered
-regularisation, and hierarchical group LASSO — via CVXPY.**
+regularisation, hierarchical group LASSO, and sparse 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/)
@@ -15,7 +15,7 @@ Y = X\beta^\top + \varepsilon,
 \qquad \beta \in \mathbb{R}^{N \times M}
 $$
 
-when three things matter:
+when four things matter:
 
 - Some coefficients **must be zero, non-negative, or non-positive**, possibly by
   asset, by factor, or both.
@@ -23,6 +23,9 @@ when three things matter:
 - 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).
+- You want to combine **group-level selection with within-group elementwise
+  sparsity** via a tunable mix of group L2 and L1 penalties (Sparse Group
+  LASSO).
 
 It is written in pure numpy/pandas/scipy/cvxpy. No numba, no custom
 coordinate descent. The solver is CVXPY (default `CLARABEL`), so problem
@@ -130,6 +133,49 @@ 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.
 
+### 4. Sparse Group LASSO
+
+Group LASSO selects whole groups in or out — every response inside an
+"active" group gets a non-zero loading. When the discovered groups are
+slightly heterogeneous (and HCGL clusters often are, especially at coarser
+`cutoff_fraction`), this admits noisy within-group loadings on responses
+that don't actually load on the factor.
+
+The `l1_weight` mixing parameter α ∈ [0, 1] adds an elementwise L1 penalty
+on top of the group L2 (Simon, Friedman, Hastie & Tibshirani 2013):
+
+$$
+\mathcal{P}(\beta) = (1 - \alpha)\,\lambda \sum_g w_g \, \|\beta_g - \beta_0\|_{2,1}
+\;+\; \alpha\,\lambda \, \|\beta - \beta_0\|_1
+$$
+
+```python
+model = LassoModel(
+    model_type=LassoModelType.GROUP_LASSO_CLUSTERS,
+    reg_lambda=1e-4,
+    cutoff_fraction=0.65,   # coarser clusters
+    l1_weight=0.10,         # α — group L2 still primary, L1 corrects within-group
+).fit(x=X, y=Y)
+```
+
+The interpretation is "group-then-prune": the group L2 term still drives
+group-level selection, while the L1 term zeros individual asset-factor
+coefficients within active groups whose contribution is noise. Setting
+`l1_weight=0.0` (the default) reduces exactly to pure group LASSO and is
+backward-compatible — the L1 term is dropped from the CVX problem entirely
+when α = 0, with zero runtime cost.
+
+Typical research range: α ∈ [0.05, 0.20]. Above ~0.30 the group structure
+stops driving the model and the result reverts toward plain LASSO. The
+penalty is centered on the same prior `β₀` as the group term, so the two
+shrinkage mechanisms compose consistently.
+
+The L1 term respects the same per-element sign constraints and the same
+prior as the group term, so all four features in this section compose: a
+single fit can simultaneously enforce sign constraints, shrink toward a
+prior, group-select via HCGL clusters, and apply within-group elementwise
+sparsity.
+
 ---
 
 ## When to use it — and when not
@@ -140,6 +186,8 @@ grouping would need to be refit anyway.
   matrix.
 - You have a prior `β₀` that should shrink the fit instead of zero.
 - You need discovered-group structured sparsity (HCGL).
+- You need group-level selection with within-group elementwise sparsity
+  (sparse group LASSO at small-to-moderate α).
 - You want a small, auditable CVXPY-based tool rather than a coordinate-descent
   library with opaque internals.
 
@@ -149,6 +197,11 @@ grouping would need to be refit anyway.
   `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 sparse group LASSO at large α (close to 1.0) or at very large
+  scale — specialised solvers like `asgl` or `SGL` handle proximal-operator
+  acceleration that the CVXPY formulation here does not. This package's
+  sparse group LASSO is intended for moderate α ∈ [0, 0.3] where the group
+  structure remains primary.
 - You need non-linear models, random effects, or GLM link functions.
 
 A feature-by-feature comparison matrix is in

{factorlasso-0.3.2 → factorlasso-0.3.4}/factorlasso/lasso_estimator.py

@@ -89,7 +89,27 @@ class LassoEstimationResult:
     estimated_beta : np.ndarray, shape (N, M)
         Factor loadings.  NaN if solver failed.
     alpha : np.ndarray, shape (N,)
-        EWMA-weighted mean residual per response variable.
+        EWMA-weighted mean of the *demeaned* residuals, per response.
+
+        Important: this is **not** the regression intercept in the original
+        ``y = α + Xβ + ε`` representation.  Because :func:`get_x_y_np` removes
+        the conditional mean of both ``y`` and ``X`` before the solver runs,
+        the model that is actually fitted is
+
+            ``y_demeaned ≈ X_demeaned · β``       (no intercept term)
+
+        and ``alpha`` here is computed *post-hoc* as the weighted mean of the
+        residuals on the demeaned data.  In particular:
+
+        * If ``span is None`` (sample-mean demeaning), this quantity is
+          identically zero by the OLS first-order condition.
+        * If ``span`` is set (one-sided EWMA demeaning), this quantity is the
+          leftover when the EWMA mean does not match the sample mean — i.e.
+          a *finite-sample EWMA-demean residual*, not an intercept.
+
+        ``LassoModel`` exposes this value as ``model.intercept_`` for
+        backward compatibility; the **economic intercept** of the regression
+        in original units is available separately as ``model.alpha_const_``.
     ss_total : np.ndarray, shape (N,)
         EWMA-weighted total variance per response variable.
     ss_res : np.ndarray, shape (N,)
@@ -114,7 +134,16 @@ def _compute_solver_diagnostics(
     estimated_beta: np.ndarray,
     weights: np.ndarray,
 ) -> Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
-    """In-sample fit diagnostics from solver weights."""
+    """In-sample fit diagnostics from solver weights.
+
+    The returned ``alpha`` is the EWMA-weighted mean of residuals on the
+    demeaned data the solver received. It is **not** the regression
+    intercept in original units; see the docstring of
+    :class:`LassoEstimationResult` for the distinction. The economic
+    intercept of ``y = α + Xβ + ε`` is computed in
+    :meth:`LassoModel.fit` from the sample means of the original (pre-
+    demean) ``y`` and ``X``, and is exposed as ``model.alpha_const_``.
+    """
     col_sums = np.sum(weights, axis=0)
     norm_w = np.divide(weights, col_sums, out=np.zeros_like(weights),
                        where=col_sums != 0)
@@ -374,6 +403,7 @@ def solve_group_lasso_cvx_problem(
     factors_beta_loading_signs: Optional[np.ndarray] = None,
     factors_beta_prior: Optional[np.ndarray] = None,
     group_penalty: str = "normalized",
+    l1_weight: float = 0.0,
 ) -> LassoEstimationResult:
     r"""
     Group LASSO multi-output regression via CVXPY.
@@ -383,14 +413,22 @@ def solve_group_lasso_cvx_problem(
     .. math::
 
         \frac{1}{T}\|W \odot (X\beta^\top - Y)\|_F^2
-        + \lambda \sum_g w_g \sum_{i \in g}
+        + (1 - \alpha)\,\lambda \sum_g w_g \sum_{i \in g}
           \|\beta_{i,:} - \beta_{0,i,:}\|_2
+        + \alpha\,\lambda \,\|\beta - \beta_0\|_1
 
     where *g* indexes groups of response variables (rows of β) and the
     per-group weight ``w_g`` is set by ``group_penalty`` (see below).
-    The inner sum is the ``L_{2,1}`` norm of the group submatrix —
-    each response's loading vector is shrunk by an L2 norm, and block
-    sparsity is driven across responses within a group.
+    The inner sum of the group term is the ``L_{2,1}`` norm of the group
+    submatrix — each response's loading vector is shrunk by an L2 norm,
+    and block sparsity is driven across responses within a group. The
+    optional L1 term drives elementwise sparsity on top, zeroing
+    individual assets whose loadings are noisy even within an "active"
+    group — the Simon–Friedman–Hastie–Tibshirani (2013) Sparse Group
+    LASSO formulation.
+
+    At ``l1_weight=0.0`` (default) the problem reduces to the previous
+    pure group LASSO and is numerically identical to v0.3.1.
 
     Parameters
     ----------
@@ -418,6 +456,18 @@ def solve_group_lasso_cvx_problem(
         The two conventions are related by a constant factor √G, so
         results under ``"yuan_lin"`` at regularisation ``λ`` match
         results under ``"normalized"`` at regularisation ``λ·√G``.
+    l1_weight : float, default 0.0
+        Sparse Group LASSO mixing parameter ``α ∈ [0, 1]``. Weight on
+        the elementwise L1 penalty term; ``(1 - α)`` weights the group
+        L2 term. Set ``α = 0`` (default) for pure group LASSO —
+        backward compatible with v0.3.1. Set ``α = 1`` for pure LASSO
+        (no group structure). Typical research values are ``α ∈
+        [0.05, 0.20]``: preserve group structure as the primary
+        selection mechanism while allowing additional within-group
+        elementwise zeroing for assets whose loadings are noisy. The
+        L1 term shrinks ``β`` toward the prior ``β_0`` elementwise,
+        consistent with the group term which also shrinks toward the
+        prior.
 
     Returns
     -------
@@ -429,6 +479,10 @@ def solve_group_lasso_cvx_problem(
             f"group_penalty must be 'normalized' or 'yuan_lin', "
             f"got {group_penalty!r}"
         )
+    if not (0.0 <= l1_weight <= 1.0):
+        raise ValueError(
+            f"l1_weight must lie in [0, 1], got {l1_weight!r}"
+        )
     assert y.ndim == 2 and x.ndim == 2 and group_loadings.ndim == 2
     assert x.shape[0] == y.shape[0] and y.shape[1] == group_loadings.shape[0]
 
@@ -464,16 +518,26 @@ def solve_group_lasso_cvx_problem(
             return float(np.sqrt(g))
         return float(np.sqrt(g / n_groups))
 
-    # Group penalty
+    # Group penalty (L_{2,1} norm within each group, scaled by (1 - α))
     masks = [
         np.isclose(group_loadings[:, g], 1.0) for g in range(n_groups)
     ]
-    penalty = cvx.sum([
+    group_pen = cvx.sum([
         reg_lambda * _weight(m)
         * cvx.sum(cvx.norm2(beta[m, :] - prior[m, :], axis=1))
         for m in masks
     ])
 
+    # Elementwise L1 penalty (scaled by α). Shrinks toward the same
+    # prior used by the group term so at α=1 the problem is consistent
+    # with plain LASSO centred on β₀. At α=0 this term vanishes and
+    # the problem reduces exactly to the v0.3.1 pure group LASSO.
+    if l1_weight > 0.0:
+        l1_pen = reg_lambda * cvx.sum(cvx.abs(beta - prior))
+        penalty = (1.0 - l1_weight) * group_pen + l1_weight * l1_pen
+    else:
+        penalty = group_pen
+
     problem = cvx.Problem(cvx.Minimize(fit + penalty), constraints) \
         if constraints else cvx.Problem(cvx.Minimize(fit + penalty))
     problem.solve(verbose=verbose, solver=solver)
@@ -559,6 +623,17 @@ class LassoModel:
         ``"yuan_lin"`` uses the classical Yuan–Lin (2006) ``√|g|``.
         Ignored for ``model_type == LASSO``.  See
         :func:`solve_group_lasso_cvx_problem` for the full formula.
+    l1_weight : float, default 0.0
+        Sparse Group LASSO mixing parameter ``α ∈ [0, 1]``. Adds an
+        elementwise L1 penalty ``α·λ·|β - β₀|`` on top of the standard
+        group L2 penalty (which is scaled by ``(1 - α)``). Set ``α = 0``
+        (default) for pure group LASSO — backward compatible with
+        v0.3.1. Typical research values: ``α ∈ [0.05, 0.20]`` — preserve
+        group structure as the primary mechanism while allowing
+        additional within-group elementwise zeroing for assets whose
+        loadings are noisy. Only consumed when ``model_type`` is
+        ``GROUP_LASSO`` or ``GROUP_LASSO_CLUSTERS``; ignored for pure
+        ``LASSO`` since L1 is the only penalty already.
     factors_beta_loading_signs : pd.DataFrame, optional
     factors_beta_prior : pd.DataFrame, optional
     demean : bool, default True
@@ -569,8 +644,31 @@ class LassoModel:
     --------------------------------------
     coef_ : pd.DataFrame, shape (N, M)
         Estimated factor loadings β.
+    alpha_const_ : pd.Series, shape (N,)
+        **Economic intercept α** — what users typically mean by "alpha"
+        when decomposing returns into ``y = α + Xβ + ε``. Reconstructed
+        from sample means of the *original* (pre-demean) ``y`` and ``X``
+        and the fitted β, so the identity ``y_mean = α + x_mean · β``
+        holds exactly. For ``span=None`` and unconstrained coefficients
+        this equals the OLS intercept exactly; for ``span=integer`` it
+        is reconstructed from sample means rather than EWMA means and
+        thus stays interpretable regardless of EWMA span.
+
+        This is the field to read when reporting the regression intercept.
     intercept_ : pd.Series, shape (N,)
-        Estimated intercept α.
+        Raw solver output: the EWMA-weighted mean of residuals on the
+        *demeaned* data, equal to ``estimation_result_.alpha``. Because
+        the underlying solver fits a no-intercept model on centered data,
+        this is a mechanical artefact of the fit, **not** the regression
+        intercept in original units:
+
+        * for ``span=None`` this is identically zero by the OLS
+          first-order condition;
+        * for ``span=integer`` it is a finite-sample EWMA-demean leftover.
+
+        Preserved under this name for back-compatibility with code that
+        read ``model.intercept_`` in pre-0.3.4 versions. New code should
+        use ``alpha_const_`` for the economic intercept.
     estimation_result_ : LassoEstimationResult
         Full diagnostics (alpha, ss_total, ss_res, r2).
     clusters_ : pd.Series or None
@@ -606,6 +704,7 @@ class LassoModel:
     span_freq_dict: Optional[Dict[str, float]] = None
     cutoff_fraction: float = DEFAULT_CUTOFF_FRACTION
     group_penalty: str = "normalized"
+    l1_weight: float = 0.0
     demean: bool = True
     solver: str = 'CLARABEL'
     warmup_period: Optional[int] = 12
@@ -618,6 +717,7 @@ class LassoModel:
     y_: Optional[pd.DataFrame] = None
     coef_: Optional[pd.DataFrame] = None
     intercept_: Optional[pd.Series] = None
+    alpha_const_: Optional[pd.Series] = None
     estimation_result_: Optional[LassoEstimationResult] = None
     clusters_: Optional[pd.Series] = None
     linkage_: Optional[np.ndarray] = None
@@ -641,6 +741,10 @@ class LassoModel:
                 f"group_penalty must be 'normalized' or 'yuan_lin', "
                 f"got {self.group_penalty!r}"
             )
+        if not (0.0 <= self.l1_weight <= 1.0):
+            raise ValueError(
+                f"l1_weight must lie in [0, 1], got {self.l1_weight!r}"
+            )
 
     # ── Backward-compatible property aliases ─────────────────────────
 
@@ -860,6 +964,7 @@ class LassoModel:
                 factors_beta_loading_signs=signs_np,
                 factors_beta_prior=prior_np,
                 group_penalty=self.group_penalty,
+                l1_weight=self.l1_weight,
             )
 
         elif self.model_type == LassoModelType.GROUP_LASSO_CLUSTERS:
@@ -903,12 +1008,14 @@ class LassoModel:
                 factors_beta_loading_signs=signs_np,
                 factors_beta_prior=prior_np,
                 group_penalty=self.group_penalty,
+                l1_weight=self.l1_weight,
             )
         else:
             raise NotImplementedError(f"Unsupported model_type: {self.model_type}")
 
         # Zero out betas for variables with insufficient history
         est_beta = result.estimated_beta
+        short_assets: Optional[pd.Index] = None
         if self.warmup_period is not None:
             n_valid = np.count_nonzero(~np.isnan(y.to_numpy()), axis=0)
             short = n_valid < self.warmup_period
@@ -916,6 +1023,14 @@ class LassoModel:
                 est_beta[short, :] = 0.0
                 for attr in ('alpha', 'ss_total', 'ss_res', 'r2'):
                     getattr(result, attr)[short] = np.nan
+                # Capture for use below — the cluster-assignment step
+                # at the end of fit() needs to drop these same assets
+                # so clusters_, coef_, and per-asset diagnostics stay
+                # mutually consistent. Without this the zeroed-beta
+                # assets would still receive spurious singleton cluster
+                # labels that inflate downstream n_clusters and pollute
+                # cluster-based risk attribution / regime diagnostics.
+                short_assets = y.columns[short]
 
         # Store fitted state (trailing underscore convention)
         self.x_ = x
@@ -925,9 +1040,35 @@ class LassoModel:
         self.coef_ = pd.DataFrame(
             est_beta, index=y.columns, columns=x.columns,
         )
+        # intercept_ : preserved from v0.3.3 — the raw solver output, namely
+        # the EWMA-weighted residual mean on the demeaned data. This is the
+        # mechanical artefact of fitting a no-intercept model on centered
+        # inputs (see :class:`LassoEstimationResult` docstring on ``alpha``).
+        # It is NOT the regression intercept in the original
+        # ``y = α + Xβ + ε`` representation; for span=None it is identically
+        # zero by construction. Kept under this name for back-compat with
+        # any analytics that read ``model.intercept_``.
         self.intercept_ = pd.Series(
             result.alpha, index=y.columns, name='intercept',
         )
+        # alpha_const_ : the economic intercept α — what users typically
+        # mean by "alpha" when decomposing returns into ``α + Xβ + ε``.
+        # Reconstructed from sample means of the *original* (pre-demean)
+        # ``y`` and ``X`` and the fitted β so the identity
+        # ``y_mean = α + x_mean · β`` holds exactly. For span=None and
+        # unconstrained coefficients this equals the OLS intercept exactly;
+        # for span=integer it remains the interpretable
+        # ``α + factor exposure`` decomposition regardless of EWMA span.
+        x_mean = np.asarray(x.mean(skipna=True).values, dtype=float)
+        y_mean = np.asarray(y.mean(skipna=True).values, dtype=float)
+        beta_arr = np.where(np.isnan(est_beta), 0.0, est_beta)
+        alpha_const_arr = y_mean - beta_arr @ x_mean
+        alpha_const_ser = pd.Series(
+            alpha_const_arr, index=y.columns, name='alpha_const',
+        )
+        if short_assets is not None:
+            alpha_const_ser.loc[short_assets] = np.nan
+        self.alpha_const_ = alpha_const_ser
         self.estimation_result_ = result
         # For GROUP_LASSO with externally supplied group_data, record it as
         # clusters_ so downstream consumers (CurrentFactorCovarData,
@@ -936,6 +1077,18 @@ class LassoModel:
         # modes. The HCGL path already sets `clusters` above.
         if clusters is None and self.model_type == LassoModelType.GROUP_LASSO:
             clusters = self.group_data.reindex(y.columns).copy()
+        # Filter out cluster labels for ghost assets — assets whose betas
+        # were zeroed above because they had fewer than ``warmup_period``
+        # valid observations. Dropping them here keeps ``clusters_``
+        # consistent with ``coef_`` (zeroed) and per-asset diagnostics
+        # (NaN), so downstream consumers that count or analyse clusters
+        # see only assets that actually contributed to the fit. Without
+        # this, pre-launch / short-history assets receive placeholder
+        # singleton labels that inflate ``n_clusters`` in early history
+        # (observed: 83 raw vs 31 real on a 160-asset multi-asset
+        # universe at 2002-12-31).
+        if clusters is not None and short_assets is not None and len(short_assets) > 0:
+            clusters = clusters.drop(short_assets, errors='ignore')
         self.clusters_ = clusters
         self.linkage_ = linkage
         self.cutoff_ = cutoff

{factorlasso-0.3.2 → factorlasso-0.3.4}/factorlasso.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: factorlasso
-Version: 0.3.2
+Version: 0.3.4
 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
@@ -45,7 +45,7 @@ Dynamic: license-file
 # factorlasso
 
 **Sparse multi-output regression with sign constraints, prior-centered
-regularisation, and hierarchical group LASSO — via CVXPY.**
+regularisation, hierarchical group LASSO, and sparse 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/)
@@ -59,7 +59,7 @@ Y = X\beta^\top + \varepsilon,
 \qquad \beta \in \mathbb{R}^{N \times M}
 $$
 
-when three things matter:
+when four things matter:
 
 - Some coefficients **must be zero, non-negative, or non-positive**, possibly by
   asset, by factor, or both.
@@ -67,6 +67,9 @@ when three things matter:
 - 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).
+- You want to combine **group-level selection with within-group elementwise
+  sparsity** via a tunable mix of group L2 and L1 penalties (Sparse Group
+  LASSO).
 
 It is written in pure numpy/pandas/scipy/cvxpy. No numba, no custom
 coordinate descent. The solver is CVXPY (default `CLARABEL`), so problem
@@ -174,6 +177,49 @@ 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.
 
+### 4. Sparse Group LASSO
+
+Group LASSO selects whole groups in or out — every response inside an
+"active" group gets a non-zero loading. When the discovered groups are
+slightly heterogeneous (and HCGL clusters often are, especially at coarser
+`cutoff_fraction`), this admits noisy within-group loadings on responses
+that don't actually load on the factor.
+
+The `l1_weight` mixing parameter α ∈ [0, 1] adds an elementwise L1 penalty
+on top of the group L2 (Simon, Friedman, Hastie & Tibshirani 2013):
+
+$$
+\mathcal{P}(\beta) = (1 - \alpha)\,\lambda \sum_g w_g \, \|\beta_g - \beta_0\|_{2,1}
+\;+\; \alpha\,\lambda \, \|\beta - \beta_0\|_1
+$$
+
+```python
+model = LassoModel(
+    model_type=LassoModelType.GROUP_LASSO_CLUSTERS,
+    reg_lambda=1e-4,
+    cutoff_fraction=0.65,   # coarser clusters
+    l1_weight=0.10,         # α — group L2 still primary, L1 corrects within-group
+).fit(x=X, y=Y)
+```
+
+The interpretation is "group-then-prune": the group L2 term still drives
+group-level selection, while the L1 term zeros individual asset-factor
+coefficients within active groups whose contribution is noise. Setting
+`l1_weight=0.0` (the default) reduces exactly to pure group LASSO and is
+backward-compatible — the L1 term is dropped from the CVX problem entirely
+when α = 0, with zero runtime cost.
+
+Typical research range: α ∈ [0.05, 0.20]. Above ~0.30 the group structure
+stops driving the model and the result reverts toward plain LASSO. The
+penalty is centered on the same prior `β₀` as the group term, so the two
+shrinkage mechanisms compose consistently.
+
+The L1 term respects the same per-element sign constraints and the same
+prior as the group term, so all four features in this section compose: a
+single fit can simultaneously enforce sign constraints, shrink toward a
+prior, group-select via HCGL clusters, and apply within-group elementwise
+sparsity.
+
 ---
 
 ## When to use it — and when not
@@ -184,6 +230,8 @@ grouping would need to be refit anyway.
   matrix.
 - You have a prior `β₀` that should shrink the fit instead of zero.
 - You need discovered-group structured sparsity (HCGL).
+- You need group-level selection with within-group elementwise sparsity
+  (sparse group LASSO at small-to-moderate α).
 - You want a small, auditable CVXPY-based tool rather than a coordinate-descent
   library with opaque internals.
 
@@ -193,6 +241,11 @@ grouping would need to be refit anyway.
   `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 sparse group LASSO at large α (close to 1.0) or at very large
+  scale — specialised solvers like `asgl` or `SGL` handle proximal-operator
+  acceleration that the CVXPY formulation here does not. This package's
+  sparse group LASSO is intended for moderate α ∈ [0, 0.3] where the group
+  structure remains primary.
 - You need non-linear models, random effects, or GLM link functions.
 
 A feature-by-feature comparison matrix is in

{factorlasso-0.3.2 → factorlasso-0.3.4}/factorlasso.egg-info/SOURCES.txt

@@ -18,4 +18,5 @@ tests/test_coverage_extras.py
 tests/test_external_parity.py
 tests/test_factorlasso.py
 tests/test_integration.py
+tests/test_l1_weight.py
 tests/test_new_features.py

{factorlasso-0.3.2 → factorlasso-0.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "factorlasso"
-version = "0.3.2"
+version = "0.3.4"
 description = "Sparse factor model estimation with sign-constrained LASSO, prior-centered regularisation, and hierarchical group LASSO (HCGL)"
 readme = "README.md"
 license = {text = "MIT"}

factorlasso-0.3.4/tests/test_l1_weight.py

@@ -0,0 +1,473 @@
+"""
+Tests for the ``l1_weight`` / Sparse Group LASSO feature (v0.3.2).
+
+Coverage:
+- Backward compatibility at ``l1_weight=0.0`` (bit-identical to v0.3.1
+  pure group LASSO).
+- LASSO mode ignores ``l1_weight`` (documented behaviour).
+- Input validation via ``LassoModel.__post_init__`` and solver-level
+  range check.
+- Mathematical limit at ``l1_weight=1.0``: group term is nuked, result
+  approximates pure LASSO.
+- Interaction with ``group_penalty``: at α=1 group scheme is irrelevant;
+  at 0<α<1 both terms are active and the choice matters.
+- Group-then-prune property: on a panel with noisy within-cluster
+  assets, increasing α progressively zeros the spurious loadings while
+  preserving genuine signal loadings.
+- Sign constraints and prior centering compose with the L1 term.
+"""
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+import pytest
+
+from factorlasso import (
+    LassoModel,
+    LassoModelType,
+    compute_clusters_from_corr_matrix,
+)
+from factorlasso.ewm_utils import compute_ewm_covar, set_group_loadings
+from factorlasso.lasso_estimator import (
+    get_x_y_np,
+    solve_group_lasso_cvx_problem,
+    solve_lasso_cvx_problem,
+)
+
+# ═══════════════════════════════════════════════════════════════════════
+# Fixtures
+# ═══════════════════════════════════════════════════════════════════════
+
+
+@pytest.fixture
+def hcgl_panel():
+    """Multi-response panel with block correlation structure suitable for HCGL."""
+    rng = np.random.default_rng(42)
+    T, M, N, n_clusters = 300, 6, 30, 5
+    X = rng.standard_normal((T, M))
+    cluster_of = rng.integers(0, n_clusters, N)
+    beta_true = np.zeros((N, M))
+    for c in range(n_clusters):
+        mask = cluster_of == c
+        factors = rng.choice(M, size=2, replace=False)
+        for f in factors:
+            beta_true[mask, f] = rng.normal(0.5, 0.15, mask.sum())
+    Y = X @ beta_true.T + 0.1 * rng.standard_normal((T, N))
+    for c in range(n_clusters):
+        mask = cluster_of == c
+        shared = rng.standard_normal(T)
+        for i in np.where(mask)[0]:
+            Y[:, i] = 0.3 * shared + 0.7 * Y[:, i]
+    X_df = pd.DataFrame(X, columns=[f"f{i}" for i in range(M)])
+    Y_df = pd.DataFrame(Y, columns=[f"y{i}" for i in range(N)])
+    return X_df, Y_df
+
+
+@pytest.fixture
+def hcgl_prepped(hcgl_panel):
+    """Pre-computed HCGL inputs: demeaned x/y, valid_mask, clusters, group loadings."""
+    X, Y = hcgl_panel
+    x_np, y_np, mask = get_x_y_np(x=X, y=Y, span=60, demean=True)
+    corr = compute_ewm_covar(a=y_np, span=60, is_corr=True)
+    corr_df = pd.DataFrame(corr, index=Y.columns, columns=Y.columns)
+    clusters, _, _ = compute_clusters_from_corr_matrix(corr_df)
+    gl = set_group_loadings(group_data=clusters).to_numpy()
+    return {
+        "X": X, "Y": Y,
+        "x_np": x_np, "y_np": y_np, "mask": mask,
+        "clusters": clusters, "group_loadings": gl,
+    }
+
+
+@pytest.fixture
+def sparsity_panel():
+    """
+    Adversarial panel: each HCGL cluster contains a few genuine-loading
+    assets and several pure-noise assets that cluster together via a
+    shared idiosyncratic shock. Tests whether l1_weight > 0 zeros out
+    the noise-asset loadings.
+    """
+    rng = np.random.default_rng(0)
+    T, M, N = 400, 5, 20
+    X = rng.standard_normal((T, M))
+    beta_true = np.zeros((N, M))
+    # First 3 assets of each half load on a factor; rest are pure noise
+    beta_true[:3, 0] = rng.normal(0.8, 0.05, 3)
+    beta_true[10:13, 1] = rng.normal(0.8, 0.05, 3)
+    Y = X @ beta_true.T + 0.1 * rng.standard_normal((T, N))
+    # Shared idiosyncratic shock within each half drives clustering
+    shared0 = rng.standard_normal(T)
+    shared1 = rng.standard_normal(T)
+    for i in range(10):
+        Y[:, i] += 0.3 * shared0
+    for i in range(10, 20):
+        Y[:, i] += 0.3 * shared1
+    X_df = pd.DataFrame(X, columns=[f"f{i}" for i in range(M)])
+    Y_df = pd.DataFrame(Y, columns=[f"y{i}" for i in range(N)])
+    # True-zero mask (which cells SHOULD be zero in β)
+    noise_mask = np.ones((N, M), dtype=bool)
+    noise_mask[:3, 0] = False     # signal
+    noise_mask[10:13, 1] = False  # signal
+    return X_df, Y_df, noise_mask
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# Backward compatibility
+# ═══════════════════════════════════════════════════════════════════════
+
+
+class TestBackwardCompatibility:
+    """Default behaviour must be bit-identical to pre-l1_weight code."""
+
+    def test_solver_default_vs_explicit_zero(self, hcgl_prepped):
+        """solve_group_lasso_cvx_problem: no kwarg ≡ l1_weight=0.0."""
+        p = hcgl_prepped
+        res_default = solve_group_lasso_cvx_problem(
+            x=p["x_np"], y=p["y_np"], group_loadings=p["group_loadings"],
+            valid_mask=p["mask"], reg_lambda=1e-4, span=60,
+        )
+        res_zero = solve_group_lasso_cvx_problem(
+            x=p["x_np"], y=p["y_np"], group_loadings=p["group_loadings"],
+            valid_mask=p["mask"], reg_lambda=1e-4, span=60,
+            l1_weight=0.0,
+        )
+        delta = np.abs(res_default.estimated_beta - res_zero.estimated_beta)
+        assert delta.max() == 0.0, (
+            f"Backward compat broken at solver level: Max |Δβ|={delta.max():.2e}"
+        )
+
+    def test_lassomodel_default_vs_explicit_zero(self, hcgl_panel):
+        """LassoModel: no kwarg ≡ l1_weight=0.0."""
+        X, Y = hcgl_panel
+        m_default = LassoModel(
+            model_type=LassoModelType.GROUP_LASSO_CLUSTERS,
+            reg_lambda=1e-4, span=60,
+        ).fit(x=X, y=Y)
+        m_zero = LassoModel(
+            model_type=LassoModelType.GROUP_LASSO_CLUSTERS,
+            reg_lambda=1e-4, span=60, l1_weight=0.0,
+        ).fit(x=X, y=Y)
+        delta = (m_default.coef_ - m_zero.coef_).abs().values.max()
+        assert delta == 0.0, (
+            f"Backward compat broken at LassoModel level: Max |Δβ|={delta:.2e}"
+        )
+
+    def test_lasso_mode_ignores_l1_weight(self, hcgl_panel):
+        """Docstring: 'ignored for pure LASSO since L1 is the only penalty already.'"""
+        X, Y = hcgl_panel
+        m0 = LassoModel(
+            model_type=LassoModelType.LASSO, reg_lambda=1e-4, span=60,
+        ).fit(x=X, y=Y)
+        m5 = LassoModel(
+            model_type=LassoModelType.LASSO, reg_lambda=1e-4, span=60,
+            l1_weight=0.5,
+        ).fit(x=X, y=Y)
+        delta = (m0.coef_ - m5.coef_).abs().values.max()
+        assert delta == 0.0
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# Input validation
+# ═══════════════════════════════════════════════════════════════════════
+
+
+class TestValidation:
+    """l1_weight must be rejected outside [0, 1] at construction and solver."""
+
+    @pytest.mark.parametrize("bad", [-0.1, -1e-9, 1.001, 2.0, np.nan, np.inf, -np.inf])
+    def test_lassomodel_rejects_bad_values(self, bad):
+        with pytest.raises(ValueError, match="l1_weight must lie in"):
+            LassoModel(l1_weight=bad)
+
+    @pytest.mark.parametrize("good", [0.0, 1e-9, 0.5, 1.0 - 1e-9, 1.0])
+    def test_lassomodel_accepts_good_values(self, good):
+        # Should not raise
+        m = LassoModel(l1_weight=good)
+        assert m.l1_weight == good
+
+    def test_solver_rejects_bad_values(self, hcgl_prepped):
+        p = hcgl_prepped
+        with pytest.raises(ValueError, match="l1_weight must lie in"):
+            solve_group_lasso_cvx_problem(
+                x=p["x_np"], y=p["y_np"], group_loadings=p["group_loadings"],
+                valid_mask=p["mask"], reg_lambda=1e-4, span=60,
+                l1_weight=1.5,
+            )
+
+    def test_get_params_includes_l1_weight(self):
+        params = LassoModel(l1_weight=0.25).get_params()
+        assert params["l1_weight"] == 0.25
+
+    def test_set_params_updates_l1_weight(self):
+        m = LassoModel()
+        assert m.l1_weight == 0.0
+        m.set_params(l1_weight=0.15)
+        assert m.l1_weight == 0.15
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# Mathematical limits
+# ═══════════════════════════════════════════════════════════════════════
+
+
+class TestLimits:
+    """Verify α=0 and α=1 endpoints match their algebraic limits."""
+
+    def test_alpha_one_approximates_pure_lasso(self, hcgl_prepped):
+        """
+        At α=1 the group term has coefficient 0, leaving only elementwise L1.
+        Result must match a pure-LASSO solve at the same λ, up to CVXPY
+        solver precision. The docstring claim 'Set α = 1 for pure LASSO
+        (no group structure)' is verified here.
+        """
+        p = hcgl_prepped
+        res_alpha1 = solve_group_lasso_cvx_problem(
+            x=p["x_np"], y=p["y_np"], group_loadings=p["group_loadings"],
+            valid_mask=p["mask"], reg_lambda=3e-4, span=60,
+            l1_weight=1.0,
+        )
+        res_pure = solve_lasso_cvx_problem(
+            x=p["x_np"], y=p["y_np"], valid_mask=p["mask"],
+            reg_lambda=3e-4, span=60,
+        )
+        delta = np.abs(res_alpha1.estimated_beta - res_pure.estimated_beta)
+        # Solver-precision tolerance — CLARABEL interior-point typically
+        # converges to ~1e-6 relative accuracy. The two problems are
+        # algebraically identical; differences are pure numerical noise.
+        assert delta.max() < 1e-4, (
+            f"α=1 should match pure LASSO; got Max |Δβ|={delta.max():.3e}"
+        )
+        assert delta.mean() < 1e-5
+
+    def test_alpha_zero_ignores_group_penalty_choice_noop(self, hcgl_prepped):
+        """
+        At α=0 only the group term is active. Verified by TestInteraction
+        below that the group_penalty choice matters here. Sanity check:
+        α=0 with either scheme still gives the expected normalization
+        default behaviour.
+        """
+        p = hcgl_prepped
+        res_norm = solve_group_lasso_cvx_problem(
+            x=p["x_np"], y=p["y_np"], group_loadings=p["group_loadings"],
+            valid_mask=p["mask"], reg_lambda=1e-4, span=60,
+            l1_weight=0.0, group_penalty="normalized",
+        )
+        # β must be finite, non-trivial
+        assert np.isfinite(res_norm.estimated_beta).all()
+        assert np.linalg.norm(res_norm.estimated_beta) > 0.1
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# Interaction with group_penalty
+# ═══════════════════════════════════════════════════════════════════════
+
+
+class TestInteraction:
+    """l1_weight × group_penalty: group-term scaling is irrelevant at α=1."""
+
+    def test_group_penalty_irrelevant_at_alpha_one(self, hcgl_prepped):
+        """At α=1 the group term has coefficient 0 → group_penalty choice is moot."""
+        p = hcgl_prepped
+        res_norm = solve_group_lasso_cvx_problem(
+            x=p["x_np"], y=p["y_np"], group_loadings=p["group_loadings"],
+            valid_mask=p["mask"], reg_lambda=3e-4, span=60,
+            l1_weight=1.0, group_penalty="normalized",
+        )
+        res_yl = solve_group_lasso_cvx_problem(
+            x=p["x_np"], y=p["y_np"], group_loadings=p["group_loadings"],
+            valid_mask=p["mask"], reg_lambda=3e-4, span=60,
+            l1_weight=1.0, group_penalty="yuan_lin",
+        )
+        delta = np.abs(res_norm.estimated_beta - res_yl.estimated_beta)
+        assert delta.max() == 0.0, (
+            f"group_penalty should be no-op at α=1; Max |Δβ|={delta.max():.2e}"
+        )
+
+    def test_group_penalty_matters_in_middle(self, hcgl_prepped):
+        """At 0<α<1 both terms active → normalized and yuan_lin diverge."""
+        p = hcgl_prepped
+        res_norm = solve_group_lasso_cvx_problem(
+            x=p["x_np"], y=p["y_np"], group_loadings=p["group_loadings"],
+            valid_mask=p["mask"], reg_lambda=3e-4, span=60,
+            l1_weight=0.5, group_penalty="normalized",
+        )
+        res_yl = solve_group_lasso_cvx_problem(
+            x=p["x_np"], y=p["y_np"], group_loadings=p["group_loadings"],
+            valid_mask=p["mask"], reg_lambda=3e-4, span=60,
+            l1_weight=0.5, group_penalty="yuan_lin",
+        )
+        delta = np.abs(res_norm.estimated_beta - res_yl.estimated_beta)
+        assert delta.max() > 1e-5, (
+            "group_penalty should matter when 0<α<1"
+        )
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# Group-then-prune — the whole point of the feature
+# ═══════════════════════════════════════════════════════════════════════
+
+
+class TestSparsityProgression:
+    """
+    The README's claim: increasing α zeros within-group noisy β.
+    This is the feature's value proposition; if it doesn't hold,
+    l1_weight is cosmetic.
+    """
+
+    def test_spurious_mass_decreases_monotonically_with_alpha(
+        self, sparsity_panel,
+    ):
+        X, Y, noise_mask = sparsity_panel
+        x_np, y_np, mask = get_x_y_np(x=X, y=Y, span=60, demean=True)
+        corr = compute_ewm_covar(a=y_np, span=60, is_corr=True)
+        clusters, _, _ = compute_clusters_from_corr_matrix(
+            pd.DataFrame(corr, index=Y.columns, columns=Y.columns)
+        )
+        gl = set_group_loadings(group_data=clusters).to_numpy()
+
+        alphas = [0.0, 0.1, 0.3, 0.5, 0.8]
+        spurious_masses = []
+        for a in alphas:
+            res = solve_group_lasso_cvx_problem(
+                x=x_np, y=y_np, group_loadings=gl,
+                valid_mask=mask, reg_lambda=5e-3, span=60,
+                l1_weight=a,
+            )
+            spurious = float(np.abs(res.estimated_beta[noise_mask]).sum())
+            spurious_masses.append(spurious)
+
+        # Non-increasing: L1 shrinkage should only reduce spurious loadings
+        for i in range(1, len(alphas)):
+            assert spurious_masses[i] <= spurious_masses[i - 1] + 1e-6, (
+                f"Spurious β mass increased from α={alphas[i-1]} "
+                f"({spurious_masses[i-1]:.4f}) to α={alphas[i]} "
+                f"({spurious_masses[i]:.4f})"
+            )
+        # And meaningfully so: at least 2x reduction from α=0 to α=0.8
+        assert spurious_masses[-1] < 0.5 * spurious_masses[0], (
+            f"L1 pruning did not fire: "
+            f"α=0 mass={spurious_masses[0]:.4f}, "
+            f"α=0.8 mass={spurious_masses[-1]:.4f}"
+        )
+
+    def test_signal_mass_preserved(self, sparsity_panel):
+        """
+        At moderate α (research range up to 0.3) the genuine-signal β
+        must survive — otherwise L1 is destroying information, not
+        cleaning noise.
+        """
+        X, Y, noise_mask = sparsity_panel
+        signal_mask = ~noise_mask
+        x_np, y_np, mask = get_x_y_np(x=X, y=Y, span=60, demean=True)
+        corr = compute_ewm_covar(a=y_np, span=60, is_corr=True)
+        clusters, _, _ = compute_clusters_from_corr_matrix(
+            pd.DataFrame(corr, index=Y.columns, columns=Y.columns)
+        )
+        gl = set_group_loadings(group_data=clusters).to_numpy()
+
+        signal_masses = {}
+        for a in [0.0, 0.1, 0.3]:
+            res = solve_group_lasso_cvx_problem(
+                x=x_np, y=y_np, group_loadings=gl,
+                valid_mask=mask, reg_lambda=5e-3, span=60,
+                l1_weight=a,
+            )
+            signal_masses[a] = float(np.abs(res.estimated_beta[signal_mask]).sum())
+
+        # Signal mass must stay within 10% of the α=0 baseline over the
+        # research range. If the L1 term hammers the signal too, the
+        # feature isn't useful.
+        baseline = signal_masses[0.0]
+        for a in [0.1, 0.3]:
+            ratio = signal_masses[a] / baseline
+            assert ratio > 0.9, (
+                f"Signal mass dropped too much at α={a}: "
+                f"{signal_masses[a]:.4f} / {baseline:.4f} = {ratio:.2f}"
+            )
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# Composition with other features
+# ═══════════════════════════════════════════════════════════════════════
+
+
+class TestComposition:
+    """l1_weight composes with sign constraints and prior centering."""
+
+    def test_sign_constraints_respected_at_all_alpha(self):
+        """
+        Sign constraints must hold regardless of l1_weight. We only test
+        non-negative and zero constraints — the non-positive constraint
+        has a known fragility to solver precision when the optimum lies
+        at zero, which is orthogonal to l1_weight.
+        """
+        rng = np.random.default_rng(7)
+        T, M, N = 200, 4, 10
+        X = pd.DataFrame(
+            rng.standard_normal((T, M)),
+            columns=[f"f{i}" for i in range(M)],
+        )
+        beta_true = rng.standard_normal((N, M))
+        # Make y0 strongly non-negative on f0
+        beta_true[0, 0] = 1.5
+        Y = pd.DataFrame(
+            X.values @ beta_true.T + 0.1 * rng.standard_normal((T, N)),
+            columns=[f"y{i}" for i in range(N)],
+        )
+        group_data = pd.Series(rng.integers(0, 3, N), index=Y.columns)
+        signs = pd.DataFrame(np.nan, index=Y.columns, columns=X.columns)
+        signs.loc["y0", "f0"] = 1   # non-negative
+        signs.loc["y2", "f0"] = 0   # zero
+
+        for alpha in [0.0, 0.1, 0.3, 0.8, 1.0]:
+            m = LassoModel(
+                model_type=LassoModelType.GROUP_LASSO,
+                group_data=group_data,
+                reg_lambda=3e-4, span=60,
+                factors_beta_loading_signs=signs,
+                l1_weight=alpha,
+            ).fit(x=X, y=Y)
+            tol = 1e-6
+            assert m.coef_.loc["y0", "f0"] >= -tol, (
+                f"Non-negative violated at α={alpha}: "
+                f"β[y0,f0]={m.coef_.loc['y0', 'f0']}"
+            )
+            assert abs(m.coef_.loc["y2", "f0"]) < tol, (
+                f"Zero-constraint violated at α={alpha}: "
+                f"β[y2,f0]={m.coef_.loc['y2', 'f0']}"
+            )
+
+    def test_prior_centering_applied_to_l1_term(self, hcgl_prepped):
+        """
+        The L1 penalty is |β - β₀|, not |β|. With a large α and a
+        non-zero prior, β should shrink toward the prior, not toward
+        zero. Tests the '|β - β₀|_1' form from the docstring.
+        """
+        p = hcgl_prepped
+        N, M = p["group_loadings"].shape[0], p["x_np"].shape[1]
+        # Pick a non-zero prior
+        prior = np.full((N, M), 0.3)
+
+        # Two solves: one with prior, one without, both at α=1 (pure L1)
+        # and huge λ (strong shrinkage).
+        res_with_prior = solve_group_lasso_cvx_problem(
+            x=p["x_np"], y=p["y_np"], group_loadings=p["group_loadings"],
+            valid_mask=p["mask"], reg_lambda=1.0, span=60,
+            l1_weight=1.0,
+            factors_beta_prior=prior,
+        )
+        res_no_prior = solve_group_lasso_cvx_problem(
+            x=p["x_np"], y=p["y_np"], group_loadings=p["group_loadings"],
+            valid_mask=p["mask"], reg_lambda=1.0, span=60,
+            l1_weight=1.0,
+        )
+        # With a non-zero prior, the shrinkage target is 0.3; without,
+        # it's 0. Mean β should be meaningfully closer to the prior.
+        mean_with = float(res_with_prior.estimated_beta.mean())
+        mean_no = float(res_no_prior.estimated_beta.mean())
+        # Prior=0.3, no-prior shrinks toward 0 → mean_no ~ 0.
+        # With prior, shrinks toward 0.3 → mean_with > mean_no.
+        assert mean_with > mean_no + 0.05, (
+            f"Prior centering not honoured by L1 term: "
+            f"mean_with_prior={mean_with:.3f} vs mean_no_prior={mean_no:.3f}"
+        )