Base regression
PortfolioOptimisers.AbstractTimeSeriesRegressionEstimator — Type
abstract type AbstractTimeSeriesRegressionEstimator <: AbstractRegressionEstimatorAbstract supertype for all time-series regression estimator types.
A subtype fits one model per asset over the observations, and returns a Regression that carries the loadings of each asset.
Interfaces
To add a time-series regression estimator, subtype AbstractTimeSeriesRegressionEstimator, keep its parameters in the fields of the struct, and add this method:
Regression
PortfolioOptimisers.regression(re::AbstractTimeSeriesRegressionEstimator, X::MatNum, F::MatNum) -> Regression: Returns the regression result of the asset returnsXon the factor returnsF.
Arguments
re: The regression estimator.X: Data matrixobservations × assetsif thedimskeyword does not exist ordims = 1,assets × observationswhendims = 2.F: Data matrixobservations × factorsif thedimskeyword does not exist ordims = 1,factors × observationswhendims = 2.
Returns
reg::Regression: The regression result, which carries the loadings matrix and the optional intercept.
Examples
The example below defines a minimal regression estimator.
julia> struct MyRegressionEstimator <: PortfolioOptimisers.AbstractTimeSeriesRegressionEstimator endjulia> function PortfolioOptimisers.regression(::MyRegressionEstimator, X::PortfolioOptimisers.MatNum, F::PortfolioOptimisers.MatNum) return PortfolioOptimisers.Regression(; M = F \ X) endjulia> regression(MyRegressionEstimator(), [1.0 2.0; 3.0 4.0; 5.0 6.0], [1.0 0.0; 0.0 1.0; 0.5 0.5])Regression M ┼ 2×2 Matrix{Float64} L ┼ 2×2 Matrix{Float64} b ┼ nothing esigma ┼ nothing edof ┼ nothing ediv ┼ nothing idx ┼ nothing ts ┴ nothingRelated
PortfolioOptimisers.AbstractCrossSectionalRegressionEstimator — Type
abstract type AbstractCrossSectionalRegressionEstimator <: AbstractRegressionEstimatorAbstract supertype for all cross-sectional regression estimator types.
A subtype fits one model per observation across the assets, and returns a CrossSectionalRegression that carries the factor returns of each observation.
Interfaces
To add a cross-sectional regression estimator, subtype AbstractCrossSectionalRegressionEstimator, keep its parameters in the fields of the struct, and add this method:
Cross-sectional regression
PortfolioOptimisers.cross_sectional_regression(cre::AbstractCrossSectionalRegressionEstimator, Z::Arr3Num, X::MatNum, W::MatNum) -> CrossSectionalRegression: Returns the cross-sectional regression of the asset returnsXon the exposure tensorZ, under the cross-sectional weightsW.
Arguments
cre: The cross-sectional regression estimator.Z: The exposure tensorassets × factors × observations. The observations are the last axis, so the design of observationt,view(Z, :, :, t), is one contiguous block. Earlier releases held the observations on the first axis. A method written for them readsZ[t, :, :], and it must now readZ[:, :, t].X: The asset returns matrixobservations × assets.W: The cross-sectional weights matrixobservations × assets.
Returns
csr::CrossSectionalRegression: The cross-sectional regression result. It carries the factor returns, the residuals, the counts and the optional intercept.
Examples
The example below defines a minimal cross-sectional regression estimator.
julia> struct MyCrossSectionalRegressionEstimator <: PortfolioOptimisers.AbstractCrossSectionalRegressionEstimator endjulia> function PortfolioOptimisers.cross_sectional_regression(::MyCrossSectionalRegressionEstimator, Z::PortfolioOptimisers.Arr3Num, X::PortfolioOptimisers.MatNum, W::PortfolioOptimisers.MatNum) f = permutedims(reduce(hcat, Z[:, :, t] \ X[t, :] for t in axes(X, 1))) eps = X - permutedims(reduce(hcat, Z[:, :, t] * f[t, :] for t in axes(X, 1))) return PortfolioOptimisers.CrossSectionalRegression(; f = f, eps = eps, n = fill(size(X, 2), size(X, 1))) endjulia> cross_sectional_regression(MyCrossSectionalRegressionEstimator(), reshape([1.0, 0.0, 0.5, 0.0, 1.0, 0.5], 3, 2, 1), [1.0 2.0 1.5], ones(1, 3))CrossSectionalRegression f ┼ 1×2 Matrix{Float64} eps ┼ 1×3 Matrix{Float64} n ┼ Vector{Int64}: [3] edof ┼ nothing b ┼ nothing h1 ┼ nothing dc ┼ nothing lv ┴ nothingRelated
PortfolioOptimisers.AbstractRegressionTarget — Type
abstract type AbstractRegressionTarget <: AbstractRegressionAlgorithmAbstract supertype for all regression target types.
A target is the model that a regression estimator fits. The family has two branches. AbstractUnpenalisedRegressionTarget holds the targets that fit the coefficients with no penalty, LinearModel and GeneralisedLinearModel. AbstractPenalisedRegressionTarget holds the targets that add a penalty on the coefficients, ElasticNet. Any other model that fits under observation weights and returns its coefficients can be a target, for example a robust M-estimator that the caller writes on top of StatsAPI. The library has no such model. The # Interfaces section below states the methods that such a model must have.
Interfaces
To add a regression target, subtype AbstractUnpenalisedRegressionTarget or AbstractPenalisedRegressionTarget, keep its parameters in the fields of the struct, and add the methods below. Each estimator reads only some of them, so a target needs only the methods of the estimators that it runs under. StepwiseRegression accepts a penalised target under :aic, :aicc and :bic alone, and its docstring states the reason of each refused pair.
| Estimator | Methods it reads |
|---|---|
CrossSectionalTargetRegression | factory, StatsAPI.fit, StatsAPI.coef, is_basis_invariant, residual_count |
TargetReturnForecast | StatsAPI.fit, StatsAPI.predict, and factory with an InterceptColumn under intercept = true |
ImpliedVolatilityRegression | factory with an InterceptColumn, StatsAPI.fit, StatsAPI.predict |
StepwiseRegression | factory with an InterceptColumn, StatsAPI.fit, StatsAPI.coef, residual_count, and StatsAPI.coeftable under PValue or the score verb of its criterion under every other criterion |
DimensionReductionRegression | factory with an InterceptColumn, StatsAPI.fit, StatsAPI.coef, residual_count, regression_target_weights |
KernelTrendPattern | StatsAPI.fit, StatsAPI.predict |
The three time-series estimators carry their target through factory, so each of them also reads factory when it gets observation weights.
factory
factory(tgt::MyRegressionTarget, w::StatsBase.AbstractWeights) -> MyRegressionTarget: Return a target that carries the observation weightswinto its fit.
The cross-sectional regression fits every observation under its cross-sectional weights, so it calls this method on each observation. factory(::AbstractRegressionTarget, ::ObsWeights) refuses a target with no such method. Without the refusal, the fit of the target ignores the weights. A target that must also accept a DynamicAbstractWeights resolves it against the design with get_observation_weights at the fit, as LinearModel does.
Arguments
tgt: The new regression target.w: The observation weights, one per row of the design that the target fits.
Returns
tgt::MyRegressionTarget: A target whose fit weighs rowibyw[i].
factory with an InterceptColumn
factory(tgt::MyRegressionTarget, ic::InterceptColumn) -> MyRegressionTarget: Return a target whose fit leaves columnic.kof the design out of the penalty.
An estimator that adds a column of ones to the design calls this method before the fit, with the index of that column. The leaf method of factory returns the target unchanged, so an unpenalised target needs no method. A penalised target that must not shrink the intercept adds one, as ElasticNet does.
Arguments
tgt: The new regression target.ic: The intercept column, which holds the index of the column of ones.
Returns
tgt::MyRegressionTarget: A target whose fit does not penalise columnic.k.
StatsAPI.fit
StatsAPI.fit(tgt::MyRegressionTarget, A::MatNum, y::VecNum) -> MyRegressionFit: Fit the target to the designAand the responsey.
Arguments
tgt: The new regression target.A: The design matrix,samples × regressors. The library adds no intercept column, because the estimator of the caller states the intercept.y: The response vector, one entry per row ofA.
Returns
m::MyRegressionFit: The fitted model.
StatsAPI.coef
StatsAPI.coef(m::MyRegressionFit) -> VecNum: Return the fitted coefficients.
Arguments
m: The fitted model thatStatsAPI.fitreturns.
Returns
b::VecNum: The coefficients, one per column of the design.
StatsAPI.predict
StatsAPI.predict(m::MyRegressionFit, A::MatNum) -> VecNum: Return the fitted response on a new design.
Arguments
m: The fitted model thatStatsAPI.fitreturns.A: The design matrix,samples × regressors, with the same columns as the design of the fit.
Returns
yhat::VecNum: The predicted response, one entry per row ofA.
StatsAPI.coeftable
StatsAPI.coeftable(m::MyRegressionFit) -> StatsBase.CoefTable: Return the coefficient table of the fit, with the p-value of each coefficient in column 4.
StepwiseRegression reads it under PValue only. It reads column 4 of the table, which is the column of the p-values in GLM. It reads one row per column of the design, in the order of the design.
Arguments
m: The fitted model thatStatsAPI.fitreturns.
Returns
ct::StatsBase.CoefTable: The coefficient table, one row per column of the design. Column 4 holds the p-values.
The score verbs
StatsAPI.aic(m::MyRegressionFit) -> Number, and the same signature forStatsAPI.aicc,StatsAPI.bic,StatsAPI.r2andStatsAPI.adjr2: Return the score of the fit that the criterion of the same name inSTEPWISE_REGRESSION_CRITERIAreads.
StepwiseRegression reads the verb of its own criterion and no other, so a target implements only the verbs of the criteria that it runs under. If the verb of the criterion has no method for the fit, the first fit raises a MethodError. A penalised fit reads its effective degrees of freedom in StatsAPI.dof, as ElasticNetFit does.
Arguments
m: The fitted model thatStatsAPI.fitreturns.
Returns
s::Number: The score of the fit. The criterion states whether a smaller or a larger score is better.
residual_count
residual_count(m::MyRegressionFit, A::MatNum) -> Real: Return the residual degrees of freedom of the fit, which the estimator writes intoedofofRegression.
residual_count(::Any, ::MatNum) counts one spent parameter for each column of A, which is the count of an unpenalised fit, so such a target needs no method. A penalised fit spends fewer, and adds a method that returns its own count, as ElasticNetFit does.
Arguments
m: The fitted model thatStatsAPI.fitreturns.A: The design of the fit.
Returns
nu::Real: The residual degrees of freedom of the fit.
regression_target_weights
regression_target_weights(tgt::MyRegressionTarget) -> Option{ObsWeights}: Return the observation weights the fit oftgtapplies, ornothingwhen it applies none.
DimensionReductionRegression rebuilds the intercept of each asset from the mean of the response. It weights that mean by these weights, so that the intercept agrees with the fit. The constructor of the estimator calls regression_target_weights(::AbstractRegressionTarget), which refuses a target with no such method. Without the refusal, the intercept ignores the weights that factory stored in the target.
Arguments
tgt: The new regression target.
Returns
w::Option{ObsWeights}: The weights thatfactory(tgt, w)stored intgt, ornothingwhentgtcarries none.
is_basis_invariant
is_basis_invariant(tgt::MyRegressionTarget) -> Bool: Return whether the fit oftgtgives the same coefficients under an invertible change of the columns of the design, mapped back to the original columns.
The carry fold of CrossSectionalFactorPrior reads it when a BatchChoice moves the dropped member of a Factor Family. That move is an invertible change of the columns. A target that returns true lets the fold keep the factor returns of each past observation, so the move runs no regression again. The default returns false, and the move then fits every past observation again.
A fit that minimises a loss of the fitted values alone, such as the weighted squared residuals, can return true. An iterative fit of such a loss, such as GeneralisedLinearModel, returns true when each of its iterates is invariant too. The fold then equals the batch fit to rounding, unless rounding stops the two bases at different iterates. A penalty on the coefficients, such as a ridge, makes the answer depend on the basis, so such a target keeps the default.
Arguments
tgt: The new regression target.
Returns
flag::Bool:truewhen the coefficients of the fit do not depend on the basis of the design.
Related
AbstractRegressionAlgorithmAbstractUnpenalisedRegressionTargetAbstractPenalisedRegressionTargetLinearModelGeneralisedLinearModelElasticNetInterceptColumnCrossSectionalTargetRegressionTargetReturnForecastImpliedVolatilityRegressionStepwiseRegressionDimensionReductionRegressionKernelTrendPatternfactoryregression_target_weightsis_basis_invariantresidual_count
PortfolioOptimisers.AbstractUnpenalisedRegressionTarget — Type
abstract type AbstractUnpenalisedRegressionTarget <: AbstractRegressionTargetAbstract supertype for the regression targets that fit their coefficients with no penalty.
LinearModel and GeneralisedLinearModel subtype it. A target of this branch fits every coefficient by its loss alone, so the inference of the fit counts one degree of freedom for each coefficient. StepwiseRegression binds its target to this branch under PValue, :r2 and :adjr2, because these criteria read p-values or a residual count that no source states for a penalised fit.
Interfaces
To add an unpenalised regression target, subtype AbstractUnpenalisedRegressionTarget, and add the methods that the # Interfaces section of AbstractRegressionTarget names for the estimators that the target runs under. The target needs no method for an InterceptColumn, because the method of AbstractRegressionTarget returns the target unchanged.
StatsAPI.fit
StatsAPI.fit(tgt::MyUnpenalisedRegressionTarget, A::MatNum, y::VecNum) -> MyRegressionFit: Fit the target to the designAand the responsey, with no penalty on the coefficients.
StepwiseRegression also reads StatsAPI.coeftable or the score verb of its criterion on the fit, as the section of AbstractRegressionTarget states.
Arguments
tgt: The new regression target.A: The design matrix,samples × regressors.y: The response vector, one entry per row ofA.
Returns
m::MyRegressionFit: The fitted model.
Related
PortfolioOptimisers.AbstractPenalisedRegressionTarget — Type
abstract type AbstractPenalisedRegressionTarget <: AbstractRegressionTargetAbstract supertype for the regression targets that add a penalty on their coefficients.
ElasticNet subtypes it. A penalty shrinks the coefficients toward zero, so the fit has fewer degrees of freedom than coefficients, and its p-values are not valid. A penalty also depends on the units of each column, so a target of this branch is not invariant to the basis of the design. An estimator that adds a column of ones names it with InterceptColumn, so that the target does not shrink the intercept.
Interfaces
To add a penalised regression target, subtype AbstractPenalisedRegressionTarget, and add the methods that the # Interfaces section of AbstractRegressionTarget names for the estimators that the target runs under. Add the method below too, so that the penalty leaves the intercept alone. Add residual_count for the fit too, because its fallback counts one spent parameter for each column.
factory
factory(tgt::MyPenalisedRegressionTarget, ic::InterceptColumn) -> MyPenalisedRegressionTarget: Return a target whose fit leaves columnic.kof the design out of the penalty.
Without this method, the method of AbstractRegressionTarget returns the target unchanged, and the fit shrinks the intercept toward zero.
Arguments
tgt: The new regression target.ic: The intercept column, which holds the index of the column of ones.
Returns
tgt::MyPenalisedRegressionTarget: A target whose fit does not penalise columnic.k.
Related
PortfolioOptimisers.InterceptColumn — Type
struct InterceptColumn{__T_k} <: AbstractAlgorithmNames the column of ones that a regression estimator adds to its design.
An estimator that adds an intercept to its design calls factory(tgt, InterceptColumn(k)) before the fit, with k the index of the column of ones. A penalised target, such as ElasticNet, then leaves that coefficient out of the penalty. An unpenalised target ignores the call. The estimator names the column, because only the estimator knows where it put the column: ImpliedVolatilityRegression and DimensionReductionRegression put it first, and TargetReturnForecast puts it last. The target does not detect a constant column, because KernelTrendPattern has a column of ones whose coefficient the penalty must shrink.
Fields
k: The index of the column of ones in the design.
Constructors
InterceptColumn(k::Integer) -> InterceptColumnValidation
k >= 1. ADomainErroris thrown otherwise.
Examples
julia> InterceptColumn(1)InterceptColumn k ┴ Int64: 1Related
PortfolioOptimisers.factory — Method
factory(tgt::AbstractRegressionTarget, w::ObsWeights)Refuse a regression target that has no method to carry observation weights into its fit.
Without this method, a target with no factory(tgt, w) method of its own goes to the generic factory. The generic method returns the target unchanged, and the fit of the target then ignores the weights. A target that the caller fits without weights, as TargetReturnForecast fits it, needs no weight method, because only a call that carries weights reaches this method.
Arguments
tgt: The regression target, which has no weight method of its own.w: Observation weights vectorobservations × 1.
Validation
- The call always throws an
ArgumentErrorthat names the methodtgtlacks. The# Interfacessection ofAbstractRegressionTargetstates that method.
Related
PortfolioOptimisers.regression_target_weights — Method
regression_target_weights(tgt::AbstractRegressionTarget)Refuse a regression target that does not state the observation weights its fit applies.
DimensionReductionRegression weights the mean of the response by the weights of its target, so it must read them. A target states them with its own method, as the # Interfaces section of AbstractRegressionTarget states. Only a target with no such method reaches this one. The constructor of the estimator calls it, so the refusal comes before a fit.
Arguments
tgt: The regression target, which has noregression_target_weightsmethod of its own.
Validation
- The call always throws an
ArgumentErrorthat names the methodtgtlacks.
Related
PortfolioOptimisers.regression_target_weights — Method
regression_target_weights(tgt::Union{LinearModel, GeneralisedLinearModel})Return the observation weights that a library target carries into its fit, or nothing.
Both targets keep the weights under the weights key of tgt.kwargs, where factory puts them. The method returns the entry as it is, so it does not resolve a DynamicAbstractWeights against a design.
Arguments
tgt: ALinearModelor aGeneralisedLinearModel.
Returns
w::Option{ObsWeights}:tgt.kwargs.weights, ornothingwhentgt.kwargshas noweightskey.
Related
PortfolioOptimisers.is_basis_invariant — Function
is_basis_invariant(tgt::Union{LinearModel, GeneralisedLinearModel}) -> Bool
is_basis_invariant(tgt::AbstractRegressionTarget) -> BoolReturn whether the fit of a regression target gives the same coefficients under an invertible change of the columns of the design, mapped back to the original columns.
Take the columns of the design times an invertible matrix as a new design. A target is invariant to the basis when its coefficients on the new design, times that matrix, are its coefficients on the old design. Then the fitted values do not change either.
A weighted least-squares fit projects the response onto the span of the design, and the change keeps the span. So LinearModel returns true, on each design of full rank. A maximum-likelihood fit reads the design through the linear predictor alone, and the change keeps the set of linear predictors, so GeneralisedLinearModel returns true too.
The fit of GeneralisedLinearModel is iterative, but each iteration is a weighted least-squares fit, and the start reads the response alone. The two bases then take the same iterates and stop at the same one, and they agree to rounding. GLM stops when the change in the deviance falls below max(rtol * deviance, atol), with rtol = 1e-6, atol = 1e-6 and maxiter = 30 by default. The kwargs of the target set the three values. A tolerance near the rounding of the deviance lets rounding stop the two bases one iteration apart, and the two answers then differ by that iteration. A tighter tolerance brings each fit nearer to the maximum-likelihood answer, and it does not bring the two bases nearer to each other.
On a rank-deficient design, GLM drops a collinear column by a pivot, so the coefficients depend on the basis. A caller that reads this method, such as cross_sectional_target_coef, fits such a design in a pivoted basis of its own. Every other target returns false, because this method cannot know whether such a target penalises its coefficients.
The carry fold of CrossSectionalFactorPrior reads the method on the target of a CrossSectionalTargetRegression, when a BatchChoice moves the dropped member of a Factor Family. A target of the caller states its answer with its own method, as the # Interfaces section of AbstractRegressionTarget states.
Arguments
tgt: The regression target.
Returns
flag::Bool:truewhen the coefficients of the fit do not depend on the basis of a design of full rank.
Examples
julia> PortfolioOptimisers.is_basis_invariant(LinearModel())truejulia> PortfolioOptimisers.is_basis_invariant(GeneralisedLinearModel())truejulia> struct RidgeTarget <: PortfolioOptimisers.AbstractPenalisedRegressionTarget endjulia> PortfolioOptimisers.is_basis_invariant(RidgeTarget())falseRelated
PortfolioOptimisers.residual_count — Method
residual_count(m, A::MatNum) -> IntegerReturn the residual degrees of freedom of a fitted regression target that states no count of its own, the number of rows of the design less its number of columns.
A fit with no penalty on a design of full rank spends one parameter for each column, so the count is the count of a projection. StepwiseRegression and DimensionReductionRegression read it, and write it into edof of Regression. CrossSectionalTargetRegression reads it for each observation, on the columns that its solve algorithm keeps, and writes it into edof of CrossSectionalRegression. The method does not read GLM.dof_residual. Under weights, GLM counts the observations as the sum of the frequency weights, and the count of the library counts the rows. A penalised fit spends fewer parameters than it has columns, so it states its own count, as residual_count(::ElasticNetFit, ::MatNum) does.
Arguments
m: The fitted model, which the method does not read.A: The design of the fit,observations × columns.
Returns
nu::Integer:size(A, 1) - size(A, 2).
Related
PortfolioOptimisers.residual_count — Method
residual_count(m::GLM.LinearModel, A::MatNum) -> Integer
residual_count(m::GLM.GeneralizedLinearModel, A::MatNum) -> IntegerReturn the residual degrees of freedom of a GLM fit, the number of rows of the design less the rank that the fit identified.
GLM fits a rank-deficient design through a pivoted Cholesky factorisation, and gives each column that its pivot drops a coefficient of zero. The fit then spends its rank, not its number of columns, so the count of residual_count(::Any, ::MatNum) is too low. StatsAPI.dof of a GLM fit counts the rank and the dispersion parameter of the family, which a LinearModel always has, so the method subtracts the dispersion parameter. On a design of full rank the count is the count of the fallback. The method reads no weights, for the reason that the fallback states. CrossSectionalTargetRegression under UncheckedSolve gives GLM a rank-deficient design, and so can StepwiseRegression on a dependent candidate set.
Arguments
m: The fitted model ofLinearModelor ofGeneralisedLinearModel.A: The design of the fit,observations × columns.
Returns
nu::Integer:size(A, 1)less the rank of the fit.
Related
PortfolioOptimisers.LinearModel — Type
struct LinearModel{__T_kwargs} <: AbstractUnpenalisedRegressionTargetFits each response by ordinary least squares through GLM.LinearModel.
The target passes its kwargs field to GLM, so every option that GLM accepts reaches the fit, and the observation weights too. The target changes one entry, weights. glm_weights scales it to the count that GLM reads, and the scale does not change the coefficients. LinearModel() is the default target of every estimator in the library that takes a regression target.
Fields
kwargs: Keyword arguments passed tofit(GLM.LinearModel, X, y; kwargs...).
Constructors
LinearModel(; kwargs::NamedTuple = (;)) -> LinearModelKeywords correspond to the struct's fields.
Examples
julia> LinearModel()LinearModel kwargs ┴ @NamedTuple{}: NamedTuple()Related
PortfolioOptimisers.GeneralisedLinearModel — Type
struct GeneralisedLinearModel{__T_args, __T_kwargs, __T_variant} <: AbstractUnpenalisedRegressionTargetFits each response by a generalised linear model through GLM.GeneralizedLinearModel.
The args field carries the response distribution and, as an option, the link function. The kwargs field carries the other GLM options. The default args = (Normal(),) with the canonical identity link gives ordinary least squares.
GLM defines $R^2$ for a fitted LinearModel only, and variant names the pseudo-$R^2$ that the :r2 and :adjr2 members of STEPWISE_REGRESSION_CRITERIA read in its place. A nothing variant takes the default of the criterion, which default_regression_criterion_variant states. A minimisation criterion reads no variant, so it ignores the field.
The fit is iterative, and kwargs sets when it stops. GLM stops when the change in the deviance falls below max(rtol * deviance, atol), with rtol = 1e-6, atol = 1e-6 and maxiter = 30 by default. A tighter tolerance, such as kwargs = (; rtol = 1e-12, atol = 1e-12), brings the fit nearer to the maximum-likelihood answer, and needs more iterations. A tolerance below the rounding of the deviance makes GLM throw.
is_basis_invariant returns true, so the carry fold of CrossSectionalFactorPrior folds a move of the dropped member of a Factor Family. The fold keeps the coefficients of the old basis, and the batch fit iterates in the new basis. The two take the same iterates and agree to rounding. When the tolerance is near the rounding of the deviance, rounding can stop the two one iteration apart at an observation. The two then differ by that iteration.
Fields
args: Positional arguments passed tofit(GLM.GeneralizedLinearModel, X, y, args...; kwargs...).
kwargs: Keyword arguments passed tofit(GLM.GeneralizedLinearModel, X, y, args...; kwargs...).
variant: Name of the pseudo-$R^2$ variant a maximisation criterion reads, ornothingto take the default of the criterion.
Constructors
GeneralisedLinearModel(; args::Tuple = (Normal(),), kwargs::NamedTuple = (;), variant::Option{Symbol} = nothing) -> GeneralisedLinearModelKeywords correspond to the struct's fields.
Validation
- If provided,
variant in PSEUDO_R2_VARIANTS, the wider of the two variant tuples.StatsAPI.adjr2acceptsADJUSTED_PSEUDO_R2_VARIANTSalone, andStepwiseRegressionrejects the other two variants when its criterion is:adjr2.
Examples
julia> GeneralisedLinearModel()GeneralisedLinearModel args ┼ Tuple{Distributions.Normal{Float64}}: (Normal(0.0, 1.0),) kwargs ┼ @NamedTuple{}: NamedTuple() variant ┴ nothingRelated
AbstractRegressionTargetLinearModelPSEUDO_R2_VARIANTSADJUSTED_PSEUDO_R2_VARIANTSSTEPWISE_REGRESSION_CRITERIAStepwiseRegressiondefault_regression_criterion_variantregression_criterion_funcStatsAPI.fit(::GeneralisedLinearModel, ::MatNum, ::VecNum)is_basis_invariant
References
- [67] J. A. Nelder and R. W. Wedderburn. Generalized linear models. Journal of the Royal Statistical Society: Series A (General) 135, 370–384 (1972). Pages 370-384. The original source of this formulation was not found. The formulation follows this work and is not checked against the original.
PortfolioOptimisers.Regression — Type
struct Regression{__T_M, __T_L, __T_b, __T_esigma, __T_edof, __T_ediv, __T_idx, __T_ts} <: AbstractLoadingsRegressionResultHolds the loadings matrix, the intercept vector, the reduced-basis loadings and the idiosyncratic covariance of a fitted factor model.
M and b are the loadings matrix and the intercept vector of the factor model, with one row per asset. L holds the loadings in the reduced basis that a dimension reduction made. It is unset when the estimator regresses on the original factors.
An unset L reads back as M. A @forward_properties swap(L, M) rule makes re.L return re.M when the caller gave no L. So a consumer that decomposes risk in the factor basis needs no Nothing branch, and isnothing(re.L) is never true. Read getfield(re, :L) to tell the unset case apart, as port_opt_view does. StepwiseRegression leaves L unset and DimensionReductionRegression sets it. size(L, 2) is then the width of the basis of the risk decomposition, which is the number of original factors under the first, and the number of retained principal components under the second.
esigma holds the idiosyncratic covariance that the fit leaves. It has the same name and the same shapes as the field of CrossSectionalFactorModel, so one reader reads either block. A regression estimator fits loadings alone and writes nothing here. The prior that lifts the factor moments fills the field, and only when that prior adds a residual block. FactorPrior and FactorBlackLittermanPrior write the residual variances of factor_lift under rsd = true, and leave the field unset under rsd = false.
edof and ediv record the count behind each idiosyncratic variance. So a consumer that corrects for the sampling error of esigma, such as ResidualInflation, reads both fields from the block, and does not guess the count. StepwiseRegression and DimensionReductionRegression write edof as the number of observations less the parameters that the fit of each asset spent, which include the intercept. The prior that writes esigma restates edof in the effective count of its variance estimator. It also writes ediv, the divisor of each variance in that count, with variance_count. A block that the caller builds by hand, or that a variance estimator with no count measures, leaves both unset.
idx and ts are the row key of the block. The loadings are one fit over the sample, so the block has no rows of its own. The key names the observations of the factor returns, and of the reconstruction of the prior result that carries the block. FactorPrior writes the key. A block that the caller builds by hand, or that another prior builds, leaves it unset. A realised factor_attribution of a cross-validation reads the key to find the observations of each fold.
Mathematical definition
\[\begin{align} \boldsymbol{x}_{t} &= \boldsymbol{b} + \mathbf{M} \boldsymbol{f}_{t} + \boldsymbol{\varepsilon}_{t}\,. \end{align}\]
Where:
- $\boldsymbol{x}_t$: Asset returns for observation $t$, the $t$-th row of the returns matrix.
- $\boldsymbol{b}$: Intercept vector $N \times 1$,
b. The term is absent whenbis unset. - $\mathbf{M}$: Loadings matrix $N \times K$ of the factor model,
M. - $\boldsymbol{f}_{t}$: Factor returns for observation $t$, the $t$-th row of the factor matrix.
- $\boldsymbol{\varepsilon}_{t}$: Residual returns for observation $t$, the part of $\boldsymbol{x}_{t}$ that the factors do not explain.
- $N$: Number of assets.
- $K$: Number of factors.
Fields
M:M: Loadings matrixassets × factors.
L:L: Loadings matrixassets × reduced_dimensionsin the reduced basis of a dimension reduction.
b:b: Regression intercept vector.
esigma:esigma: Idiosyncratic covariance. A vector holds the variances alone, and a matrix holds the full covariance.
edof:edof: Degrees of freedom of each residual series, one entry per asset. It is the effective count of the observations that measure the variance of the asset, less the parameters that the fit spent on the asset. A regression estimator writes it over equally weighted observations, and a prior that writesesigmarestates it in the count of its variance estimator.
ediv:ediv: Divisor of each idiosyncratic variance, one entry per asset, in the effective count ofedof. The variance is the weighted residual sum of squares in that count, divided by this entry. A prior that writesesigmawrites it.
idx: Position of each observation that the prior result describes, in the returns data that the prior read, ornothing. A Scenario Cap keeps the last observations alone, so the positions are then the last positions of the data.
ts: Timestamp of each observation thatidxnames, ornothingwhen the returns data that the prior read carries no timestamps. When the folds of a cross-validation carry timestamps too, afactor_attributionmatches the two by timestamp, so a prior fitted on other returns data still finds its observations.
Constructors
Regression(; M::MatNum, L::Option{<:MatNum} = nothing, b::Option{<:VecNum} = nothing, esigma::Option{<:VecNum_MatNum} = nothing, edof::Option{<:VecNum} = nothing, ediv::Option{<:VecNum} = nothing, idx::Option{<:VecInt} = nothing, ts::Option{<:VecDate} = nothing) -> RegressionKeywords correspond to the struct's fields.
Validation
!isempty(M).- If provided,
!isempty(b), andlength(b) == size(M, 1). - If provided,
!isempty(L), andsize(L, 1) == size(M, 1). - If provided,
!isempty(esigma), andesigmacarriessize(M, 1)entries when it is a vector, or is square withsize(M, 1)rows when it is a matrix. - If provided,
edofandediveach carrysize(M, 1)entries. assert_row_key_partonidxand onts. When both are provided,length(ts) == length(idx).
Examples
julia> Regression(; M = [1 2 3; 4 5 6], L = [1 2 3 4; 5 6 7 8], b = [1, 2], esigma = [0.1, 0.2])Regression M ┼ 2×3 Matrix{Int64} L ┼ 2×4 Matrix{Int64} b ┼ Vector{Int64}: [1, 2] esigma ┼ Vector{Float64}: [0.1, 0.2] edof ┼ nothing ediv ┼ nothing idx ┼ nothing ts ┴ nothingRelated
References
- [12] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 4.1, Equations 4.2-4.3. The original source of this formulation was not found. The formulation follows this work and is not checked against the original.
PortfolioOptimisers.factory — Method
factory(re::LinearModel, w::ObsWeights) -> LinearModelReturn a new LinearModel regression target with observation weights w added to the keyword arguments.
Algorithm
- Merge
wintore.kwargsunder the keyweights. The merge replaces an entry that is already there. The result is the keyword arguments of the new target. - Build a new
LinearModelfrom them.
Arguments
re: The regression target.w: Observation weights vectorobservations × 1.
Returns
re::LinearModel: A new regression target that holds the weights inkwargs.
Related
StatsAPI.fit — Method
StatsAPI.fit(tgt::LinearModel, X::MatNum, y::VecNum)Fit an ordinary least-squares model with a LinearModel target.
Algorithm
- Resolve and scale the
weightsentry oftgt.kwargswithglm_fit_kwargs. Call the resultkwargs. Weights that are notStatsBase.FrequencyWeightsthen sum to their Kish effective sample size, so the inference of the fit reads that count of observations. - Call
StatsAPI.fit(GLM.LinearModel, X, y; kwargs...), and return the fitted model.
Arguments
tgt: The regression target, which holds the options of the model.X: The design matrixobservations × factors.y: The response vector.
Returns
model::GLM.LinearModel: The fitted linear model of theGLMpackage.
Related
PortfolioOptimisers.factory — Method
factory(re::GeneralisedLinearModel, w::ObsWeights) -> GeneralisedLinearModelReturn a new GeneralisedLinearModel regression target with observation weights w added to the keyword arguments.
Algorithm
- Merge
wintore.kwargsunder the keyweights. The merge replaces an entry that is already there. The result is the keyword arguments of the new target. - Rebuild
rewith the new keyword arguments throughrebuild_struct, withre.argsandre.variantunchanged.
Arguments
re: The regression target.w: Observation weights vectorobservations × 1.
Returns
re::GeneralisedLinearModel: A new regression target that holds the weights inkwargs.
Related
StatsAPI.fit — Method
StatsAPI.fit(tgt::GeneralisedLinearModel, X::MatNum, y::VecNum)Fit a generalised linear model with a GeneralisedLinearModel target.
Algorithm
- Resolve and scale the
weightsentry oftgt.kwargswithglm_fit_kwargs. Call the resultkwargs. Weights that are notStatsBase.FrequencyWeightsthen sum to their Kish effective sample size, so the inference of the fit reads that count of observations. - Call
StatsAPI.fit(GLM.GeneralizedLinearModel, X, y, tgt.args...; kwargs...), and return the fitted model.
Arguments
tgt: The regression target, which holds the options of the model.X: The design matrixobservations × factors.y: The response vector.
Returns
model::GLM.GeneralizedLinearModel: The fitted generalised linear model of theGLMpackage.
Related
PortfolioOptimisers.regression — Method
regression(re::Regression, args...)Return the regression result unchanged.
A caller that holds a RegE_Reg can call regression on it, whether it is an estimator or a result. On a Regression, the call returns its argument, so the caller needs no branch.
Arguments
re: The regression result.args...: More arguments, which the method ignores.
Returns
re::Regression: The inputre, unchanged.
Related
PortfolioOptimisers.regression — Method
regression(re::AbstractTimeSeriesRegressionEstimator, rd::ReturnsResult)Fit a time-series regression estimator to the asset returns and the factor returns of a ReturnsResult.
The method calls regression(re, X, rd.F) on the observations that it keeps. A Regression result is not an estimator, so it does not reach this method. The regression method of a result returns the result unchanged.
Algorithm
- Check that
rdcarries both matrices, as# Validationstates. - Read the source of
rewithreturns_source, and call itx_src. A regression that reads the returns data itself states its source in itsx_srcfield. - With
shared_series_fit, drop the observations at which a factor return is not finite. Underx_src = ExcessSource(), also drop the observations of a gap of a vector benchmark. A regression on such an observation has no regressor for any asset. Each fixed observation weight in the tree ofreloses the same observations. - Read the asset returns with
benchmark_relative_returnsunderx_src, and call themX.Xisrd.X, orrd.X - rd.BunderExcessSource(). - Call
regression(re, X, rd.F)on the kept observations, and return its result.
Arguments
re: The time-series regression estimator.rd: The returns result, which carries the asset returnsXand the factor returnsF.
Validation
!isnothing(rd.X). A regression needs the asset returns it explains.!isnothing(rd.F). A regression needs the factor returns it explains them with.- The rules of
benchmark_relative_returns. Sox_src = PriorSource()throws anArgumentError, because the call gives no Prior Result, andx_src = ExcessSource()refuses returns data with no benchmark.
Returns
reg::Regression: The fitted regression result.
Related
PortfolioOptimisers.port_opt_view — Method
port_opt_view(re::Regression, i)Return a view of a Regression result that keeps the assets that i selects.
The new result restricts the loadings matrix M, the optional reduced-basis loadings L, the intercept vector b, the idiosyncratic covariance esigma and the counts edof and ediv to the selected assets.
Algorithm
- Read
Landbwithgetfield, never through property access. Theswap(L, M)rule ofRegressionmakesre.Lreturnre.MwhenLis unset. So a property read puts a view ofMin theLfield of the new result, and the new result no longer shows thatLwas unset. - Take a row view of
Moveri. These are the loadings of the selected assets. - Take a row view of
Loveriwhen step 1 found a matrix, andnothingotherwise. - Take an element view of
boveriwhen step 1 found a vector, andnothingotherwise. - View
esigmawithidiosyncratic_covariance_view, which reads its shape: a vector of variances is indexed once, and a full covariance is indexed on both axes. - View
edofandedivwithnothing_scalar_array_view, which indexes a vector once and passesnothingthrough. - Build a new
Regressionfrom the six views and the unchanged row keyidxandts. The constructor runs all its guards again. The key names observations, so an asset selection does not change it.
Arguments
re: The regression result.i: The indices of the assets to keep.
Returns
reg::Regression: A new regression result. Each field with one entry per asset holds the selected assets alone.
Examples
julia> re = Regression(; M = [1 2; 3 4; 5 6], L = [10 20; 30 40; 50 60], b = [7, 8, 9])Regression M ┼ 3×2 Matrix{Int64} L ┼ 3×2 Matrix{Int64} b ┼ Vector{Int64}: [7, 8, 9] esigma ┼ nothing edof ┼ nothing ediv ┼ nothing idx ┼ nothing ts ┴ nothingjulia> PortfolioOptimisers.port_opt_view(re, [1, 3])Regression M ┼ 2×2 SubArray{Int64, 2, Matrix{Int64}, Tuple{Vector{Int64}, Base.Slice{Base.OneTo{Int64}}}, false} L ┼ 2×2 SubArray{Int64, 2, Matrix{Int64}, Tuple{Vector{Int64}, Base.Slice{Base.OneTo{Int64}}}, false} b ┼ SubArray{Int64, 1, Vector{Int64}, Tuple{Vector{Int64}}, false}: [7, 9] esigma ┼ nothing edof ┼ nothing ediv ┼ nothing idx ┼ nothing ts ┴ nothingRelated
PortfolioOptimisers.obs_weights_view — Method
obs_weights_view(tgt::Union{LinearModel, GeneralisedLinearModel}, i)Return a library target whose observation weights are cut to the observations i.
A target keeps its weights in tgt.kwargs, outside the tags of @propagatable, so it needs this method of obs_weights_view. A cut of the observations of a fit, such as the drop of a Shared Series gap, then cuts the weights of the regression too, see shared_series_estimator.
Algorithm
- Read the weights with
regression_target_weights. Returntgtwhen it holds none. - Otherwise index them with
obs_weights_index, and put them back withfactory.
Arguments
tgt: ALinearModelor aGeneralisedLinearModel.i: The observations to keep: a mask of the full sample, or their positions.
Validation
- The rules of
obs_weights_index.
Returns
tgt: The target with its weights at the kept observations.
Related
References
- [12]
- D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025).
- [67]
- J. A. Nelder and R. W. Wedderburn. Generalized linear models. Journal of the Royal Statistical Society: Series A (General) 135, 370–384 (1972).