structboost.allboost¶

structboost.allboost(sourcemat: ndarray[tuple[Any, ...], dtype[floating]], targetmat: ndarray[tuple[Any, ...], dtype[floating]], *, mandatory_features: ndarray[tuple[Any, ...], dtype[int64]] | list[ndarray[tuple[Any, ...], dtype[int64]]] | None = None, mandatory_ridge: float | ndarray[tuple[Any, ...], dtype[floating]] = 0.0, beta_init: ndarray[tuple[Any, ...], dtype[floating]] | None = None, covcache: ndarray[tuple[Any, ...], dtype[floating]] | dict[int, ndarray[tuple[Any, ...], dtype[float64]]] | None = None, col_norms_sq: ndarray[tuple[Any, ...], dtype[floating]] | None = None, stepno: int = 20, nu: float = 0.1, csf: float = 0.9, independent: bool = True, return_history: Literal[False] = False, return_covcache: Literal[False] = False) → ndarray[tuple[Any, ...], dtype[floating]][source]¶

structboost.allboost(sourcemat: ndarray[tuple[Any, ...], dtype[floating]], targetmat: ndarray[tuple[Any, ...], dtype[floating]], *, mandatory_features: ndarray[tuple[Any, ...], dtype[int64]] | list[ndarray[tuple[Any, ...], dtype[int64]]] | None = None, mandatory_ridge: float | ndarray[tuple[Any, ...], dtype[floating]] = 0.0, beta_init: ndarray[tuple[Any, ...], dtype[floating]] | None = None, covcache: ndarray[tuple[Any, ...], dtype[floating]] | dict[int, ndarray[tuple[Any, ...], dtype[float64]]] | None = None, col_norms_sq: ndarray[tuple[Any, ...], dtype[floating]] | None = None, stepno: int = 20, nu: float = 0.1, csf: float = 0.9, independent: bool = True, return_history: Literal[True], return_covcache: Literal[False] = False) → tuple[ndarray[tuple[Any, ...], dtype[floating]], AllboostHistory]

structboost.allboost(sourcemat: ndarray[tuple[Any, ...], dtype[floating]], targetmat: ndarray[tuple[Any, ...], dtype[floating]], *, mandatory_features: ndarray[tuple[Any, ...], dtype[int64]] | list[ndarray[tuple[Any, ...], dtype[int64]]] | None = None, mandatory_ridge: float | ndarray[tuple[Any, ...], dtype[floating]] = 0.0, beta_init: ndarray[tuple[Any, ...], dtype[floating]] | None = None, covcache: ndarray[tuple[Any, ...], dtype[floating]] | dict[int, ndarray[tuple[Any, ...], dtype[float64]]] | None = None, col_norms_sq: ndarray[tuple[Any, ...], dtype[floating]] | None = None, stepno: int = 20, nu: float = 0.1, csf: float = 0.9, independent: bool = True, return_history: Literal[False] = False, return_covcache: Literal[True] = False) → tuple[ndarray[tuple[Any, ...], dtype[floating]], ndarray[tuple[Any, ...], dtype[floating]] | dict[int, ndarray[tuple[Any, ...], dtype[float64]]]]

structboost.allboost(sourcemat: ndarray[tuple[Any, ...], dtype[floating]], targetmat: ndarray[tuple[Any, ...], dtype[floating]], *, mandatory_features: ndarray[tuple[Any, ...], dtype[int64]] | list[ndarray[tuple[Any, ...], dtype[int64]]] | None = None, mandatory_ridge: float | ndarray[tuple[Any, ...], dtype[floating]] = 0.0, beta_init: ndarray[tuple[Any, ...], dtype[floating]] | None = None, covcache: ndarray[tuple[Any, ...], dtype[floating]] | dict[int, ndarray[tuple[Any, ...], dtype[float64]]] | None = None, col_norms_sq: ndarray[tuple[Any, ...], dtype[floating]] | None = None, stepno: int = 20, nu: float = 0.1, csf: float = 0.9, independent: bool = True, return_history: Literal[True], return_covcache: Literal[True]) → tuple[ndarray[tuple[Any, ...], dtype[floating]], AllboostHistory, ndarray[tuple[Any, ...], dtype[floating]] | dict[int, ndarray[tuple[Any, ...], dtype[float64]]]]

Componentwise L2 boosting for multivariate regression.

Parameters:

sourcemat (ndarray of shape (n_samples, n_features)) – Predictor matrix. Standardization (z-transform) is recommended but not required; the algorithm uses actual column norms internally.
targetmat (ndarray of shape (n_samples, n_targets)) – Target matrix. For optimal boosting performance, targets should be standardized (zero mean, unit variance per column) before passing to this function.
mandatory_features (ndarray of shape (n_mandatory,) or list of ndarrays, optional) –
Features that are forcibly updated in each boosting step using a joint multivariate OLS pre-step (Binder & Schumacher, 2008, Approach B). Must be integer positions; boolean masks and float arrays are rejected rather than silently reinterpreted. If an ndarray is provided, it is applied to all targets. If a list is provided, it must have length n_targets with one 1D index array per target.

These features are always part of the unpenalized adjustment block, so they are never subject to competitive selection. That is a statement about the model specification, not about the fitted values: a mandatory feature whose contribution is estimated as zero will have a zero coefficient. If you need a guaranteed non-zero support, this is not that mechanism.
mandatory_ridge (float or ndarray of shape (n_features,), default=0) – Optional non-negative ridge penalty for mandatory coefficients, relative to each predictor’s squared norm. A scalar applies to all mandatory features; an array permits selective stabilization. Zero preserves the Binder & Schumacher (2008) unpenalized mandatory update.
beta_init (ndarray of shape (n_targets, n_features), optional) –
Starting coefficients per target. Boosting normally begins from the zero model; supplying beta_init starts it from the offset model F_0 = sourcemat @ beta_init[t] instead, so the procedure fits the correction to an externally supplied model rather than the model itself. This is the classical boosting offset (Bühlmann & Hothorn 2007, Sec. 2) and is used by BAE.from_reference() to anchor transferred encoder weights.

The learning-rate and penalty state (nuvec/penvec) still starts fresh, so features carrying a non-zero initial coefficient compete as though never selected. Pre-ageing the csf state would require the selection counts that produced beta_init, which are not part of the coefficient matrix. Deviation from beta_init is therefore bounded by stepno and does not accumulate across repeated calls.
covcache (ndarray or dict, optional) – Predictor covariance cache. A pre-computed X.T @ X ndarray uses the full-cache fast path. A dict maps feature indices to covariance columns and grows only when a feature is selected. If None, an empty column cache is created. Reuse the returned cache with the same sourcemat only.
col_norms_sq (ndarray of shape (n_features,), optional) – Pre-computed squared column norms, as returned by column_norms_sq(). Computed internally when None. Supplying it skips an O(n*p) pass and a full (n_samples, n_features) temporary per call, which matters when allboost is called repeatedly against an unchanging sourcemat – once per training iteration, in structboost.BAE.fit(). It carries the same staleness contract as covcache: reuse it with the same sourcemat only.
stepno (int, default=20) – Number of boosting iterations per target.
nu (float, default=0.1) – Learning rate. Adapts per feature via csf after each selection.
csf (float, default=0.9) – Cumulative shrinkage factor. After selection: nuvec[j] = 1 - (1 - nuvec[j])^csf. csf < 1 promotes diversity, csf > 1 reinforces selected features.
independent (bool, default=True) – If True, reset learning rate and penalty vectors for each target (no cross-target effects). Recommended for marker gene discovery. Note: the internal predictor–predictor covariance cache depends only on sourcemat and is therefore shared across targets for efficiency. If False, parameters persist across targets.
return_history (bool, default=False) – If True, also return an AllboostHistory object containing the selected feature at each step and the coefficient path (after each step).
return_covcache (bool, default=False) – If True, also return the (possibly lazily computed) covariance cache. Useful when covcache was not provided and you want to reuse it later.

Returns:

betamat (ndarray of shape (n_targets, n_features)) – Coefficient matrix (always returned).
history (AllboostHistory) – Returned as second element if return_history=True.
covcache_out (ndarray or dict) – Returned as last element if return_covcache=True. When no cache was supplied, this is a dict containing only computed covariance columns.

Return type:

ndarray[tuple[Any, …], dtype[floating]] | tuple[ndarray[tuple[Any, …], dtype[floating]], AllboostHistory] | tuple[ndarray[tuple[Any, …], dtype[floating]], ndarray[tuple[Any, …], dtype[floating]] | dict[int, ndarray[tuple[Any, …], dtype[float64]]]] | tuple[ndarray[tuple[Any, …], dtype[floating]], AllboostHistory, ndarray[tuple[Any, …], dtype[floating]] | dict[int, ndarray[tuple[Any, …], dtype[float64]]]]

Notes

Features are selected by the penalized variance-reduction (score) criterion (x_j' r)^2 / (||x_j||^2 + penvec_j) — the reduction in penalized RSS from a ridge step on feature j. This is scale-invariant in the predictor columns and gives unbiased model selection (Hofner et al. 2011).

The unbiasedness is worth spelling out, because it rests on the penalty rather than on the criterion alone. Hofner et al. show that boosting selects without bias when the base-learners are comparable in degrees of freedom. Initializing penvec_j = ||x_j||^2 * (1/nu - 1) does exactly that: the effective ridge degrees of freedom of feature j are ||x_j||^2 / (||x_j||^2 + penvec_j) = nu, the same for every feature whatever its column norm, and the criterion reduces to nu * (x_j' r)^2 / ||x_j||^2. Penalty adaptation (csf) then moves features off that common footing deliberately, which is the diversity mechanism rather than a selection bias. An earlier formulation selected on the squared shrunken coefficient (x_j' r / (||x_j||^2 + penvec_j))^2, which favors low-norm features and matches the score criterion only for equal column norms (standardized predictors). The coefficient update is unchanged.

References

Binder, H. & Schumacher, M. (2009). Incorporating pathway information into boosting estimation of high-dimensional risk prediction models. BMC Bioinformatics 10, 18. (Source of the algorithm: componentwise L2 boosting with the nu/csf penalty-adaptation mechanism.)

Binder, H. & Schumacher, M. (2008). Allowing for mandatory covariates in boosting estimation of sparse high-dimensional survival models. BMC Bioinformatics 9, 14. (Mandatory-covariate pre-step used by mandatory_features.)

Hofner, B., Hothorn, T., Kneib, T. & Schmid, M. (2011). A Framework for Unbiased Model Selection Based on Boosting. JCGS 20(4). (Penalized variance-reduction selection criterion.)

Bühlmann, P. & Hothorn, T. (2007). Boosting Algorithms: Regularization, Prediction and Model Fitting. Statistical Science 22(4), 477-505. (Offset / initial-model formulation used by beta_init.)