optimization¶
optimizer.optimization
¶
Portfolio optimization models.
Includes Mean-Risk, Risk Budgeting, Maximum Diversification, HRP, HERC, NCO, Benchmark Tracking, naive baselines (Equal Weighted, Inverse Volatility), ensemble (Stacking) optimisation, robust mean-risk with ellipsoidal uncertainty sets, bootstrap covariance uncertainty, and distributionally robust CVaR over a Wasserstein ball.
BenchmarkTrackerConfig
dataclass
¶
Immutable configuration for :class:skfolio.optimization.BenchmarkTracker.
Minimises tracking error against benchmark returns (passed as y in
fit(X, y)). Non-serialisable objects (prior_estimator,
previous_weights, groups, linear_constraints) are passed as
keyword arguments to the factory function.
Parameters¶
risk_measure : RiskMeasureType Risk measure for tracking error (default: standard deviation). min_weights : float or None Lower bound on asset weights. max_weights : float or None Upper bound on asset weights. max_short : float or None Maximum short position. max_long : float or None Maximum long position. cardinality : int or None Maximum number of assets. transaction_costs : float Linear transaction costs. management_fees : float Linear management fees. l1_coef : float L1 regularisation coefficient. l2_coef : float L2 regularisation coefficient. risk_free_rate : float Risk-free rate. solver : str CVXPY solver name. solver_params : dict or None Additional solver parameters. prior_config : MomentEstimationConfig or None Inner prior configuration.
ClusteringConfig
dataclass
¶
Immutable configuration for hierarchical clustering.
Parameters¶
max_clusters : int or None
Maximum number of flat clusters. None uses the
Two-Order Difference to Gap Statistic heuristic.
linkage_method : LinkageMethodType
Linkage method for building the dendrogram.
DistanceConfig
dataclass
¶
Immutable configuration for a distance estimator.
Parameters¶
distance_type : DistanceType
Which distance estimator to build.
absolute : bool
Whether to apply absolute transformation to the correlation
matrix (Pearson, Kendall, Spearman, Covariance distances).
power : float
Exponent of the power transformation applied to the
correlation matrix.
threshold : float
Distance correlation threshold (only for DISTANCE_CORRELATION).
DistanceType
¶
Bases: str, Enum
Distance estimator selection.
Maps to the distance classes in :mod:skfolio.distance.
EqualWeightedConfig
dataclass
¶
Immutable configuration for :class:skfolio.optimization.EqualWeighted.
The equal-weighted portfolio assigns identical weight to each asset (1/N). No estimation is required.
ExtraRiskMeasureType
¶
Bases: str, Enum
Non-convex risk measure selection (for HRP/HERC).
Maps to :class:skfolio.measures.ExtraRiskMeasure.
HERCConfig
dataclass
¶
Immutable config for HERC optimisation.
Wraps :class:skfolio.optimization.HierarchicalEqualRiskContribution.
Parameters¶
risk_measure : RiskMeasureType
Convex risk measure.
extra_risk_measure : ExtraRiskMeasureType or None
Non-convex risk measure (overrides risk_measure when set).
min_weights : float or None
Lower bound on asset weights.
max_weights : float or None
Upper bound on asset weights.
solver : str
CVXPY solver name.
solver_params : dict or None
Additional solver parameters.
distance_config : DistanceConfig or None
Distance estimator configuration.
clustering_config : ClusteringConfig or None
Hierarchical clustering configuration.
prior_config : MomentEstimationConfig or None
Inner prior configuration.
HRPConfig
dataclass
¶
Immutable configuration for :class:skfolio.optimization.HierarchicalRiskParity.
Parameters¶
risk_measure : RiskMeasureType
Convex risk measure.
extra_risk_measure : ExtraRiskMeasureType or None
Non-convex risk measure (overrides risk_measure when set).
min_weights : float or None
Lower bound on asset weights.
max_weights : float or None
Upper bound on asset weights.
distance_config : DistanceConfig or None
Distance estimator configuration.
clustering_config : ClusteringConfig or None
Hierarchical clustering configuration.
prior_config : MomentEstimationConfig or None
Inner prior configuration.
InverseVolatilityConfig
dataclass
¶
Immutable config for :class:skfolio.optimization.InverseVolatility.
Scales each position inversely to its estimated volatility.
Parameters¶
prior_config : MomentEstimationConfig or None Inner prior configuration (covariance estimator determines volatility estimates).
LinkageMethodType
¶
Bases: str, Enum
Linkage method selection for hierarchical clustering.
Maps to :class:skfolio.cluster.LinkageMethod.
MaxDiversificationConfig
dataclass
¶
Immutable configuration for :class:skfolio.optimization.MaximumDiversification.
Parameters¶
min_weights : float or None Lower bound on asset weights. max_weights : float or None Upper bound on asset weights. budget : float or None Portfolio budget (sum of weights). max_short : float or None Maximum short position. max_long : float or None Maximum long position. cardinality : int or None Maximum number of assets. l1_coef : float L1 regularisation coefficient. l2_coef : float L2 regularisation coefficient. risk_free_rate : float Risk-free rate. solver : str CVXPY solver name. solver_params : dict or None Additional solver parameters. prior_config : MomentEstimationConfig or None Inner prior configuration.
MeanRiskConfig
dataclass
¶
Immutable configuration for :class:skfolio.optimization.MeanRisk.
Serialisable parameters only. Non-serialisable objects
(prior_estimator, previous_weights, groups,
linear_constraints, etc.) are passed as keyword arguments
to the factory function.
Parameters¶
objective : ObjectiveFunctionType
Objective function.
risk_measure : RiskMeasureType
Convex risk measure.
risk_aversion : float
Risk-aversion coefficient (MAXIMIZE_UTILITY).
efficient_frontier_size : int or None
Number of points on the efficient frontier (None = single
portfolio).
min_weights : float or None
Lower bound on asset weights.
max_weights : float or None
Upper bound on asset weights.
budget : float or None
Portfolio budget (sum of weights).
max_short : float or None
Maximum short position.
max_long : float or None
Maximum long position.
cardinality : int or None
Maximum number of assets.
transaction_costs : float
Linear transaction costs penalising turnover relative to
previous_weights.
management_fees : float
Linear management fees proportional to position size.
max_tracking_error : float or None
Maximum tracking error relative to benchmark returns
(passed as y in fit(X, y)).
l1_coef : float
L1 regularisation coefficient.
l2_coef : float
L2 regularisation coefficient.
risk_free_rate : float
Risk-free rate for ratio objectives.
cvar_beta : float
CVaR confidence level.
evar_beta : float
EVaR confidence level.
cdar_beta : float
CDaR confidence level.
edar_beta : float
EDaR confidence level.
solver : str
CVXPY solver name.
solver_params : dict or None
Additional solver parameters.
prior_config : MomentEstimationConfig or None
Inner prior configuration.
for_min_variance()
classmethod
¶
Minimum-variance portfolio.
for_max_sharpe()
classmethod
¶
Maximum Sharpe-ratio portfolio.
for_max_utility(risk_aversion=1.0)
classmethod
¶
Maximum utility portfolio.
for_min_cvar(beta=0.95)
classmethod
¶
Minimum-CVaR portfolio.
for_efficient_frontier(size=20, risk_measure=RiskMeasureType.VARIANCE)
classmethod
¶
Efficient frontier with size portfolios.
NCOConfig
dataclass
¶
Immutable config for NCO optimisation.
Wraps :class:skfolio.optimization.NestedClustersOptimization.
The inner_estimator and outer_estimator are passed as factory
arguments (not stored here) because they are not serialisable.
Parameters¶
quantile : float Quantile for portfolio selection across cross-validation folds. n_jobs : int or None Number of parallel jobs for cross-validation. distance_config : DistanceConfig or None Distance estimator configuration. clustering_config : ClusteringConfig or None Hierarchical clustering configuration.
ObjectiveFunctionType
¶
Bases: str, Enum
Objective function selection.
Maps to :class:skfolio.optimization.convex._base.ObjectiveFunction.
RatioMeasureType
¶
Bases: str, Enum
Ratio measure selection for scoring (e.g. stacking meta-optimiser).
Most members map directly to :class:skfolio.measures.RatioMeasure.
INFORMATION_RATIO is implemented as a custom scorer (active return
divided by tracking error) because skfolio does not expose it natively;
use :func:~optimizer.scoring.build_scorer with a benchmark_returns
argument to build the corresponding callable.
RiskBudgetingConfig
dataclass
¶
Immutable configuration for :class:skfolio.optimization.RiskBudgeting.
The risk_budget array is passed as a factory argument (not stored
here) because numpy arrays are not hashable in frozen dataclasses.
Parameters¶
risk_measure : RiskMeasureType Convex risk measure. min_weights : float or None Lower bound on asset weights. max_weights : float or None Upper bound on asset weights. risk_free_rate : float Risk-free rate. cvar_beta : float CVaR confidence level. evar_beta : float EVaR confidence level. cdar_beta : float CDaR confidence level. edar_beta : float EDaR confidence level. solver : str CVXPY solver name. solver_params : dict or None Additional solver parameters. prior_config : MomentEstimationConfig or None Inner prior configuration.
RiskMeasureType
¶
Bases: str, Enum
Convex risk measure selection.
Maps to :class:skfolio.measures.RiskMeasure.
StackingConfig
dataclass
¶
Immutable config for :class:skfolio.optimization.StackingOptimization.
Combines multiple optimisers into an ensemble via a meta-optimiser.
The estimators list and final_estimator are passed as factory
arguments (not stored here) because they are not serialisable.
Parameters¶
quantile : float
Quantile for portfolio selection across cross-validation folds.
quantile_measure : RatioMeasureType
Ratio measure used when selecting the quantile portfolio.
n_jobs : int or None
Number of parallel jobs for cross-validation.
cv : int or None
Number of cross-validation folds (None = no cross-validation).
DRCVaRConfig
dataclass
¶
Immutable configuration for distributionally robust CVaR optimization.
Finds the allocation that minimises the worst-case CVaR over all
probability distributions within a Wasserstein ball of radius epsilon
centred at the empirical distribution::
min_w sup_{P ∈ B_ε(P̂)} CVaR_α^P(w)
Parameters¶
epsilon : float
Wasserstein ball radius ε ≥ 0. Larger values produce more
conservative, diversified portfolios. epsilon=0 recovers
standard empirical CVaR minimisation exactly.
alpha : float
CVaR confidence level α ∈ (0, 1). Passed as cvar_beta
to skfolio.
risk_aversion : float
Risk-aversion coefficient λ for the utility formulation when
epsilon > 0::
max_w μ̂ᵀw − λ · worst-case-CVaR_α(w)
``lambda=1`` (default) balances expected return and CVaR.
Ignored when ``epsilon=0``.
norm : int
Wasserstein norm order. Only norm=2 (L2) is supported by
the current skfolio backend. Any other value raises
ValueError at construction time.
min_weights : float or None
Lower bound on asset weights.
max_weights : float or None
Upper bound on asset weights.
budget : float or None
Portfolio budget (sum of weights).
max_short : float or None
Maximum short position.
max_long : float or None
Maximum long position.
risk_free_rate : float
Risk-free rate.
solver : str
CVXPY solver name. MOSEK is preferred for large instances;
CLARABEL is the open-source default.
solver_params : dict or None
Additional solver parameters.
prior_config : MomentEstimationConfig or None
Inner prior configuration. None uses skfolio's default
empirical prior.
RegimeRiskConfig
dataclass
¶
Configuration for Markov-driven blended risk measure optimisation.
Attributes¶
regime_measures : tuple[RiskMeasureType, ...]
One :class:RiskMeasureType per HMM state (index = state label).
E.g. (VARIANCE, CVAR) means state-0 uses variance and state-1
uses CVaR. Must match HMMResult.n_states.
hmm_config : HMMConfig
HMM hyper-parameters used when fitting inside the pipeline.
cvar_beta : float
Confidence level for CVaR / ES computation (default 0.95 = 95th
percentile).
CovarianceUncertaintyResult
dataclass
¶
Result of bootstrap covariance uncertainty estimation.
Attributes¶
cov_hat : np.ndarray, shape (n_assets, n_assets)
Sample covariance matrix estimated from the full return series.
delta : float
Frobenius-norm confidence radius: the (1-alpha) quantile of
‖Σ_b - Σ̂‖_F across B stationary bootstrap samples.
cov_samples : np.ndarray, shape (B, n_assets, n_assets)
Bootstrap covariance estimates, one per bootstrap resample.
RobustConfig
dataclass
¶
Immutable configuration for robust mean-risk optimization.
Implements ellipsoidal uncertainty sets for μ (and optionally Σ) to hedge against estimation error in the input parameters.
The robust objective modifies the standard mean-risk problem by assuming the true mean lies within the ellipsoid U_μ and optimising for the worst-case expected return::
min_w ρ(w) subject to min_{μ ∈ U_μ} μᵀw ≥ target
The worst-case mean within U_μ is::
min_{μ ∈ U_μ} μᵀw = μ̂ᵀw − κ · ‖S_μ^(1/2) · w‖₂
so the penalty grows with κ and with the portfolio's exposure to estimation uncertainty.
When cov_uncertainty=True and cov_uncertainty_method="bootstrap"
a stationary block bootstrap is used (via arch) to construct a
skfolio BootstrapCovarianceUncertaintySet. The "empirical"
method falls back to EmpiricalCovarianceUncertaintySet.
Parameters¶
kappa : float
Ellipsoidal uncertainty radius for μ. Larger κ produces more
conservative (diversified) portfolios. kappa=0 recovers the
standard (non-robust) MeanRisk exactly.
cov_uncertainty : bool
If True, also apply a covariance uncertainty set to hedge against
covariance estimation error. The method is controlled by
cov_uncertainty_method.
cov_uncertainty_method : str
Method for covariance uncertainty set construction.
"bootstrap" (default) uses stationary block bootstrap via
BootstrapCovarianceUncertaintySet; "empirical" uses the
formula-based EmpiricalCovarianceUncertaintySet.
B : int
Number of bootstrap resamples for the stationary block bootstrap
(only used when cov_uncertainty_method="bootstrap").
block_size : int
Expected block length for the stationary bootstrap (≈ 1 trading
month). Only used when cov_uncertainty_method="bootstrap".
bootstrap_alpha : float
Significance level for the covariance uncertainty ellipsoid; the
BootstrapCovarianceUncertaintySet confidence level is set to
1 - bootstrap_alpha. Only used when
cov_uncertainty_method="bootstrap".
mean_risk_config : MeanRiskConfig or None
Embedded mean-risk configuration (objective, risk measure,
weight bounds, …). None uses MeanRiskConfig() defaults
(minimum-variance, long-only, fully invested).
for_conservative()
classmethod
¶
Conservative robust portfolio (κ=2.0).
Suitable when estimation uncertainty is high (short history, non-stationary markets).
for_moderate()
classmethod
¶
Moderate robust portfolio (κ=1.0).
Balanced trade-off between estimation uncertainty and expected return.
for_aggressive()
classmethod
¶
Mildly robust portfolio (κ=0.5).
Closer to the standard mean-risk solution; retains most of the in-sample expected return while still penalising extreme concentration.
for_bootstrap_covariance()
classmethod
¶
Robust portfolio with bootstrap covariance uncertainty (κ=1.0).
Combines mean-vector robustness (κ=1.0) with stationary block bootstrap covariance uncertainty to hedge against both sources of estimation error.
build_dr_cvar(config=None, *, prior_estimator=None, **kwargs)
¶
Build a distributionally robust CVaR optimiser from config.
Dispatches to:
-
ε=0 — :class:
skfolio.optimization.MeanRiskwithMINIMIZE_RISKandCVAR. Identical to standard CVaR minimisation on the empirical distribution. -
ε>0 — :class:
skfolio.optimization.DistributionallyRobustCVaRwithwasserstein_ball_radius=epsilon. Solves the Wasserstein DRO reformulation via the built-in SOCP.
Wasserstein norm note
~~~~~~~~~~~~~~~~~~~~~
Only norm=2 (L2-Wasserstein) is supported. The config enforces
this via __post_init__ validation.
Parameters¶
config : DRCVaRConfig or None
DRO-CVaR configuration. Defaults to DRCVaRConfig()
(ε=0.001, α=0.95, long-only, fully invested).
prior_estimator : BasePrior or None
Prior estimator. When None, one is built from
config.prior_config (or skfolio's empirical default).
**kwargs
Additional keyword arguments forwarded to the underlying
skfolio constructor (e.g. groups, linear_constraints,
previous_weights).
Returns¶
MeanRisk
When epsilon=0: standard CVaR-minimising :class:MeanRisk.
DistributionallyRobustCVaR
When epsilon>0: Wasserstein DRO-CVaR optimiser.
build_benchmark_tracker(config=None, *, prior_estimator=None, **kwargs)
¶
Build a skfolio :class:BenchmarkTracker optimiser from config.
The resulting model minimises tracking error against benchmark
returns. Pass benchmark returns as y in model.fit(X, y).
Parameters¶
config : BenchmarkTrackerConfig or None
Benchmark tracker configuration. Defaults to
BenchmarkTrackerConfig().
prior_estimator : BasePrior or None
Prior estimator. When None, one is built from
config.prior_config (or skfolio default).
**kwargs
Additional keyword arguments forwarded to the
:class:BenchmarkTracker constructor (for non-serialisable
parameters such as previous_weights, groups,
linear_constraints).
Returns¶
BenchmarkTracker A fitted-ready skfolio optimiser.
build_clustering_estimator(config=None)
¶
build_distance_estimator(config=None, *, covariance_estimator=None)
¶
Build a skfolio distance estimator from config.
Parameters¶
config : DistanceConfig or None
Distance configuration. Defaults to DistanceConfig()
(Pearson distance).
covariance_estimator : BaseCovariance or None
Covariance estimator for CovarianceDistance. Ignored
for other distance types.
Returns¶
BaseDistance A fitted-ready skfolio distance estimator.
build_equal_weighted(config=None, **kwargs)
¶
build_herc(config=None, *, prior_estimator=None, distance_estimator=None, **kwargs)
¶
Build a skfolio HERC optimiser from config.
Parameters¶
config : HERCConfig or None
HERC configuration. Defaults to HERCConfig() (variance).
prior_estimator : BasePrior or None
Prior estimator.
distance_estimator : BaseDistance or None
Distance estimator. When None, one is built from
config.distance_config (or skfolio default).
**kwargs
Additional keyword arguments forwarded to the
:class:HierarchicalEqualRiskContribution constructor.
Returns¶
HierarchicalEqualRiskContribution A fitted-ready skfolio optimiser.
build_hrp(config=None, *, prior_estimator=None, distance_estimator=None, **kwargs)
¶
Build a skfolio :class:HierarchicalRiskParity optimiser from config.
Parameters¶
config : HRPConfig or None
HRP configuration. Defaults to HRPConfig() (variance).
prior_estimator : BasePrior or None
Prior estimator.
distance_estimator : BaseDistance or None
Distance estimator. When None, one is built from
config.distance_config (or skfolio default).
**kwargs
Additional keyword arguments forwarded to the
:class:HierarchicalRiskParity constructor.
Returns¶
HierarchicalRiskParity A fitted-ready skfolio optimiser.
build_inverse_volatility(config=None, *, prior_estimator=None, **kwargs)
¶
Build a skfolio :class:InverseVolatility optimiser from config.
Parameters¶
config : InverseVolatilityConfig or None
Configuration. Defaults to InverseVolatilityConfig().
prior_estimator : BasePrior or None
Prior estimator (covariance estimator determines volatility).
When None, one is built from config.prior_config
(or skfolio default).
**kwargs
Additional keyword arguments forwarded to the
:class:InverseVolatility constructor.
Returns¶
InverseVolatility A fitted-ready skfolio optimiser.
build_max_diversification(config=None, *, prior_estimator=None, **kwargs)
¶
Build a skfolio :class:MaximumDiversification optimiser from config.
Parameters¶
config : MaxDiversificationConfig or None
Configuration. Defaults to MaxDiversificationConfig().
prior_estimator : BasePrior or None
Prior estimator. When None, one is built from
config.prior_config (or skfolio default).
**kwargs
Additional keyword arguments forwarded to the
:class:MaximumDiversification constructor.
Returns¶
MaximumDiversification A fitted-ready skfolio optimiser.
build_mean_risk(config=None, *, prior_estimator=None, factor_exposure_constraints=None, **kwargs)
¶
Build a skfolio :class:MeanRisk optimiser from config.
Parameters¶
config : MeanRiskConfig or None
Mean-risk configuration. Defaults to MeanRiskConfig()
(minimum-variance).
prior_estimator : BasePrior or None
Prior estimator. When None, one is built from
config.prior_config (or skfolio default).
factor_exposure_constraints : FactorExposureConstraints or None
Enforceable factor exposure constraints produced by
:func:~optimizer.factors.build_factor_exposure_constraints.
When provided, left_inequality and right_inequality are
injected into the :class:MeanRisk constructor. Any explicit
left_inequality / right_inequality entries in kwargs
take precedence.
**kwargs
Additional keyword arguments forwarded to the
:class:MeanRisk constructor (for non-serialisable
parameters such as previous_weights, groups,
linear_constraints, etc.).
Returns¶
MeanRisk A fitted-ready skfolio optimiser.
build_nco(config=None, *, inner_estimator=None, outer_estimator=None, distance_estimator=None, **kwargs)
¶
Build a skfolio :class:NestedClustersOptimization optimiser from config.
Parameters¶
config : NCOConfig or None
NCO configuration. Defaults to NCOConfig().
inner_estimator : BaseOptimization or None
Inner cluster optimiser.
outer_estimator : BaseOptimization or None
Outer (inter-cluster) optimiser.
distance_estimator : BaseDistance or None
Distance estimator. When None, one is built from
config.distance_config (or skfolio default).
**kwargs
Additional keyword arguments forwarded to the
:class:NestedClustersOptimization constructor.
Returns¶
NestedClustersOptimization A fitted-ready skfolio optimiser.
build_risk_budgeting(config=None, *, risk_budget=None, prior_estimator=None, **kwargs)
¶
Build a skfolio :class:RiskBudgeting optimiser from config.
Parameters¶
config : RiskBudgetingConfig or None
Risk-budgeting configuration. Defaults to
RiskBudgetingConfig() (variance risk parity).
risk_budget : ndarray or None
Per-asset risk budget. None gives equal budgets.
prior_estimator : BasePrior or None
Prior estimator. When None, one is built from
config.prior_config (or skfolio default).
**kwargs
Additional keyword arguments forwarded to the
:class:RiskBudgeting constructor.
Returns¶
RiskBudgeting A fitted-ready skfolio optimiser.
build_stacking(config=None, *, estimators=None, final_estimator=None, **kwargs)
¶
Build a skfolio :class:StackingOptimization ensemble from config.
Parameters¶
config : StackingConfig or None
Stacking configuration. Defaults to StackingConfig().
estimators : list of (name, estimator) tuples or None
Sub-optimisers whose outputs are combined. Required by
skfolio but passed here (not in config) because estimator
objects are not serialisable.
final_estimator : BaseOptimization or None
Meta-optimiser that allocates across sub-portfolios.
**kwargs
Additional keyword arguments forwarded to the
:class:StackingOptimization constructor.
Returns¶
StackingOptimization A fitted-ready skfolio ensemble optimiser.
build_regime_blended_optimizer(config, hmm_result, **mean_risk_kwargs)
¶
Return a MeanRisk optimizer configured for the dominant regime.
Because skfolio's MeanRisk requires a single convex risk measure,
this function selects the risk measure of the dominant regime —
the state s* = argmax_s γ_T(s) — and builds a standard
:class:skfolio.optimization.MeanRisk with that measure.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
RegimeRiskConfig
|
Regime risk configuration. |
required |
hmm_result
|
HMMResult
|
Fitted HMM providing current regime probabilities. |
required |
**mean_risk_kwargs
|
object
|
Additional keyword arguments forwarded to
:class: |
{}
|
Returns:
| Type | Description |
|---|---|
MeanRisk
|
class: |
MeanRisk
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
build_regime_risk_budgeting(config, hmm_result, regime_budgets, **kwargs)
¶
Return a RiskBudgeting optimizer with a regime-blended budget vector.
Computes b_t = Σ_s γ_T(s) · b_s from the current HMM state
probabilities and injects the result as risk_budget into
:func:build_risk_budgeting.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
RiskBudgetingConfig
|
Risk-budgeting configuration (risk measure, constraints, …). |
required |
hmm_result
|
HMMResult
|
Fitted HMM providing current filtered state probabilities. |
required |
regime_budgets
|
list[NDArray[float64]]
|
One budget vector per HMM state, each shape
|
required |
**kwargs
|
object
|
Additional keyword arguments forwarded to
:func: |
{}
|
Returns:
| Type | Description |
|---|---|
RiskBudgeting
|
class: |
RiskBudgeting
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
compute_blended_risk_measure(returns, weights, hmm_result, regime_measures, cvar_beta=0.95)
¶
Compute ρ_t(w) = Σ_s γ_T(s) · ρ_s(w): probability-weighted blended risk.
Each regime's risk ρ_s(w) is computed on the historical portfolio returns
from periods assigned to that regime (hard Viterbi-style assignment via
argmax of filtered probabilities). Regimes with fewer than
_MIN_REGIME_SAMPLES observations fall back to full-sample risk.
The blend weights γ_T(s) are the last row of
hmm_result.filtered_probs — the most-recent filtered state
probabilities, which sum to 1 by HMM construction.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
returns
|
DataFrame
|
Dates × assets matrix of linear returns. |
required |
weights
|
NDArray[float64]
|
1-D array of portfolio weights, shape |
required |
hmm_result
|
HMMResult
|
Fitted HMM with |
required |
regime_measures
|
Sequence[RiskMeasureType]
|
One :class: |
required |
cvar_beta
|
float
|
CVaR confidence level (used when a regime uses CVaR). |
0.95
|
Returns:
| Type | Description |
|---|---|
float
|
Scalar non-negative blended risk value. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
ValueError
|
If weights length does not match returns columns. |
compute_regime_budget(regime_budgets, filtered_probs_last)
¶
Compute b_t = Σ_s γ_T(s) · b_s: probability-weighted blended budget.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
regime_budgets
|
list[NDArray[float64]]
|
One budget vector per HMM state, each shape
|
required |
filtered_probs_last
|
NDArray[float64]
|
Current state probabilities γ_T, shape
|
required |
Returns:
| Type | Description |
|---|---|
NDArray[float64]
|
Blended budget vector of shape |
NDArray[float64]
|
to 1. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
bootstrap_covariance_uncertainty(returns, B=500, block_size=21, alpha=0.05, seed=None)
¶
Estimate covariance uncertainty via stationary block bootstrap.
Draws B bootstrap resamples from returns using a stationary block
bootstrap (preserving autocorrelation structure), estimates the sample
covariance for each resample, and reports the Frobenius-norm confidence
radius as the (1-alpha) quantile of ‖Σ_b - Σ̂‖_F.
The Frobenius-norm confidence set is::
{ Σ : ‖Σ - Σ̂‖_F ≤ δ }
Parameters¶
returns : pd.DataFrame, shape (T, n_assets)
Linear asset returns (rows = observations, columns = assets).
B : int, default=500
Number of bootstrap resamples.
block_size : int, default=21
Expected block length for the stationary bootstrap (≈ 1 trading
month). Larger values preserve more autocorrelation at the cost of
bootstrap variance.
alpha : float, default=0.05
Significance level; delta is the (1-alpha) quantile of
Frobenius distances.
seed : int or None, default=None
Random seed for reproducibility.
Returns¶
CovarianceUncertaintyResult
Dataclass with cov_hat, delta, and cov_samples.
build_robust_mean_risk(config=None, *, prior_estimator=None, **kwargs)
¶
Build a robust :class:MeanRisk optimiser with ellipsoidal uncertainty sets.
Injects skfolio's mu_uncertainty_set_estimator into a standard
MeanRisk to hedge against estimation error in the expected return
vector μ. Optionally adds covariance uncertainty via stationary block
bootstrap (cov_uncertainty_method="bootstrap", default) or the
analytic formula (cov_uncertainty_method="empirical").
Kappa–confidence_level mapping
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
At fit time, n_assets is known and the conversion is::
confidence_level = F_{χ²_{n_assets}}(κ²)
This ensures the ellipsoid half-width equals κ regardless of n_assets.
Special case kappa=0
~~~~~~~~~~~~~~~~~~~~~~~~
When kappa=0, no uncertainty set is injected, so the optimiser is
identical to the output of :func:build_mean_risk with the same
mean_risk_config.
Parameters¶
config : RobustConfig or None
Robust configuration. Defaults to RobustConfig() (κ=1.0,
min-variance objective, no covariance uncertainty).
prior_estimator : BasePrior or None
Prior estimator. When None, one is built from
config.mean_risk_config.prior_config (or skfolio default).
**kwargs
Additional keyword arguments forwarded to the :class:MeanRisk
constructor (e.g. previous_weights, groups,
linear_constraints).
Returns¶
MeanRisk A fitted-ready skfolio optimiser with ellipsoidal uncertainty sets.