Base regression

PortfolioOptimisers.AbstractTimeSeriesRegressionEstimator — Type
abstract type AbstractTimeSeriesRegressionEstimator <: AbstractRegressionEstimator

Abstract 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 returns X on the factor returns F.

Arguments

  • re: The regression estimator.
  • X: Data matrix observations × assets if the dims keyword does not exist or dims = 1, assets × observations when dims = 2.
  • F: Data matrix observations × factors if the dims keyword does not exist or dims = 1, factors × observations when dims = 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 ┴ nothing

Related

source
PortfolioOptimisers.AbstractCrossSectionalRegressionEstimator — Type
abstract type AbstractCrossSectionalRegressionEstimator <: AbstractRegressionEstimator

Abstract 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 returns X on the exposure tensor Z, under the cross-sectional weights W.

Arguments

  • cre: The cross-sectional regression estimator.
  • Z: The exposure tensor assets × factors × observations. The observations are the last axis, so the design of observation t, view(Z, :, :, t), is one contiguous block. Earlier releases held the observations on the first axis. A method written for them reads Z[t, :, :], and it must now read Z[:, :, t].
  • X: The asset returns matrix observations × assets.
  • W: The cross-sectional weights matrix observations × 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 ┴ nothing

Related

source
PortfolioOptimisers.AbstractRegressionTarget — Type
abstract type AbstractRegressionTarget <: AbstractRegressionAlgorithm

Abstract 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.

EstimatorMethods it reads
CrossSectionalTargetRegressionfactory, StatsAPI.fit, StatsAPI.coef, is_basis_invariant, residual_count
TargetReturnForecastStatsAPI.fit, StatsAPI.predict, and factory with an InterceptColumn under intercept = true
ImpliedVolatilityRegressionfactory with an InterceptColumn, StatsAPI.fit, StatsAPI.predict
StepwiseRegressionfactory 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
DimensionReductionRegressionfactory with an InterceptColumn, StatsAPI.fit, StatsAPI.coef, residual_count, regression_target_weights
KernelTrendPatternStatsAPI.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 weights w into 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 row i by w[i].

factory with an InterceptColumn

  • factory(tgt::MyRegressionTarget, ic::InterceptColumn) -> MyRegressionTarget: Return a target whose fit leaves column ic.k of 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 column ic.k.

StatsAPI.fit

  • StatsAPI.fit(tgt::MyRegressionTarget, A::MatNum, y::VecNum) -> MyRegressionFit: Fit the target to the design A and the response y.

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 of A.

Returns

  • m::MyRegressionFit: The fitted model.

StatsAPI.coef

  • StatsAPI.coef(m::MyRegressionFit) -> VecNum: Return the fitted coefficients.

Arguments

  • m: The fitted model that StatsAPI.fit returns.

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 that StatsAPI.fit returns.
  • 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 of A.

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 that StatsAPI.fit returns.

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 for StatsAPI.aicc, StatsAPI.bic, StatsAPI.r2 and StatsAPI.adjr2: Return the score of the fit that the criterion of the same name in STEPWISE_REGRESSION_CRITERIA reads.

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 that StatsAPI.fit returns.

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 into edof of Regression.

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 that StatsAPI.fit returns.
  • 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 of tgt applies, or nothing when 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 that factory(tgt, w) stored in tgt, or nothing when tgt carries none.

is_basis_invariant

  • is_basis_invariant(tgt::MyRegressionTarget) -> Bool: Return whether the fit of tgt gives 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: true when the coefficients of the fit do not depend on the basis of the design.

Related

source
PortfolioOptimisers.AbstractUnpenalisedRegressionTarget — Type
abstract type AbstractUnpenalisedRegressionTarget <: AbstractRegressionTarget

Abstract 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 design A and the response y, 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 of A.

Returns

  • m::MyRegressionFit: The fitted model.

Related

source
PortfolioOptimisers.AbstractPenalisedRegressionTarget — Type
abstract type AbstractPenalisedRegressionTarget <: AbstractRegressionTarget

Abstract 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 column ic.k of 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 column ic.k.

Related

source
PortfolioOptimisers.InterceptColumn — Type
struct InterceptColumn{__T_k} <: AbstractAlgorithm

Names 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) -> InterceptColumn

Validation

  • k >= 1. A DomainError is thrown otherwise.

Examples

julia> InterceptColumn(1)InterceptColumn  k ┴ Int64: 1

Related

source
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 vector observations × 1.

Validation

  • The call always throws an ArgumentError that names the method tgt lacks. The # Interfaces section of AbstractRegressionTarget states that method.

Related

source
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 no regression_target_weights method of its own.

Validation

  • The call always throws an ArgumentError that names the method tgt lacks.

Related

source
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

Returns

  • w::Option{ObsWeights}: tgt.kwargs.weights, or nothing when tgt.kwargs has no weights key.

Related

source
PortfolioOptimisers.is_basis_invariant — Function
is_basis_invariant(tgt::Union{LinearModel, GeneralisedLinearModel}) -> Bool
is_basis_invariant(tgt::AbstractRegressionTarget) -> Bool

Return 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: true when 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())false

Related

source
PortfolioOptimisers.residual_count — Method
residual_count(m, A::MatNum) -> Integer

Return 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

source
PortfolioOptimisers.residual_count — Method
residual_count(m::GLM.LinearModel, A::MatNum) -> Integer
residual_count(m::GLM.GeneralizedLinearModel, A::MatNum) -> Integer

Return 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

Returns

  • nu::Integer: size(A, 1) less the rank of the fit.

Related

source
PortfolioOptimisers.LinearModel — Type
struct LinearModel{__T_kwargs} <: AbstractUnpenalisedRegressionTarget

Fits 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 to fit(GLM.LinearModel, X, y; kwargs...).

Constructors

LinearModel(;    kwargs::NamedTuple = (;)) -> LinearModel

Keywords correspond to the struct's fields.

Examples

julia> LinearModel()LinearModel  kwargs ┴ @NamedTuple{}: NamedTuple()

Related

source
PortfolioOptimisers.GeneralisedLinearModel — Type
struct GeneralisedLinearModel{__T_args, __T_kwargs, __T_variant} <: AbstractUnpenalisedRegressionTarget

Fits 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 to fit(GLM.GeneralizedLinearModel, X, y, args...; kwargs...).
  • kwargs: Keyword arguments passed to fit(GLM.GeneralizedLinearModel, X, y, args...; kwargs...).
  • variant: Name of the pseudo-$R^2$ variant a maximisation criterion reads, or nothing to take the default of the criterion.

Constructors

GeneralisedLinearModel(;    args::Tuple = (Normal(),),    kwargs::NamedTuple = (;),    variant::Option{Symbol} = nothing) -> GeneralisedLinearModel

Keywords correspond to the struct's fields.

Validation

Examples

julia> GeneralisedLinearModel()GeneralisedLinearModel     args ┼ Tuple{Distributions.Normal{Float64}}: (Normal(0.0, 1.0),)   kwargs ┼ @NamedTuple{}: NamedTuple()  variant ┴ nothing

Related

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.
source
PortfolioOptimisers.Regression — Type
struct Regression{__T_M, __T_L, __T_b, __T_esigma, __T_edof, __T_ediv, __T_idx, __T_ts} <: AbstractLoadingsRegressionResult

Holds 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 when b is 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 matrix assets × factors.
  • L: L: Loadings matrix assets × reduced_dimensions in 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 writes esigma restates it in the count of its variance estimator.
  • ediv: ediv: Divisor of each idiosyncratic variance, one entry per asset, in the effective count of edof. The variance is the weighted residual sum of squares in that count, divided by this entry. A prior that writes esigma writes it.
  • idx: Position of each observation that the prior result describes, in the returns data that the prior read, or nothing. A Scenario Cap keeps the last observations alone, so the positions are then the last positions of the data.
  • ts: Timestamp of each observation that idx names, or nothing when the returns data that the prior read carries no timestamps. When the folds of a cross-validation carry timestamps too, a factor_attribution matches 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) -> Regression

Keywords correspond to the struct's fields.

Validation

  • !isempty(M).
  • If provided, !isempty(b), and length(b) == size(M, 1).
  • If provided, !isempty(L), and size(L, 1) == size(M, 1).
  • If provided, !isempty(esigma), and esigma carries size(M, 1) entries when it is a vector, or is square with size(M, 1) rows when it is a matrix.
  • If provided, edof and ediv each carry size(M, 1) entries.
  • assert_row_key_part on idx and on ts. 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 ┴ nothing

Related

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.
source
PortfolioOptimisers.factory — Method
factory(re::LinearModel, w::ObsWeights) -> LinearModel

Return a new LinearModel regression target with observation weights w added to the keyword arguments.

Algorithm

  1. Merge w into re.kwargs under the key weights. The merge replaces an entry that is already there. The result is the keyword arguments of the new target.
  2. Build a new LinearModel from them.

Arguments

  • re: The regression target.
  • w: Observation weights vector observations × 1.

Returns

  • re::LinearModel: A new regression target that holds the weights in kwargs.

Related

source
StatsAPI.fit — Method
StatsAPI.fit(tgt::LinearModel, X::MatNum, y::VecNum)

Fit an ordinary least-squares model with a LinearModel target.

Algorithm

  1. Resolve and scale the weights entry of tgt.kwargs with glm_fit_kwargs. Call the result kwargs. Weights that are not StatsBase.FrequencyWeights then sum to their Kish effective sample size, so the inference of the fit reads that count of observations.
  2. 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 matrix observations × factors.
  • y: The response vector.

Returns

  • model::GLM.LinearModel: The fitted linear model of the GLM package.

Related

source
PortfolioOptimisers.factory — Method
factory(re::GeneralisedLinearModel, w::ObsWeights) -> GeneralisedLinearModel

Return a new GeneralisedLinearModel regression target with observation weights w added to the keyword arguments.

Algorithm

  1. Merge w into re.kwargs under the key weights. The merge replaces an entry that is already there. The result is the keyword arguments of the new target.
  2. Rebuild re with the new keyword arguments through rebuild_struct, with re.args and re.variant unchanged.

Arguments

  • re: The regression target.
  • w: Observation weights vector observations × 1.

Returns

  • re::GeneralisedLinearModel: A new regression target that holds the weights in kwargs.

Related

source
StatsAPI.fit — Method
StatsAPI.fit(tgt::GeneralisedLinearModel, X::MatNum, y::VecNum)

Fit a generalised linear model with a GeneralisedLinearModel target.

Algorithm

  1. Resolve and scale the weights entry of tgt.kwargs with glm_fit_kwargs. Call the result kwargs. Weights that are not StatsBase.FrequencyWeights then sum to their Kish effective sample size, so the inference of the fit reads that count of observations.
  2. 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 matrix observations × factors.
  • y: The response vector.

Returns

  • model::GLM.GeneralizedLinearModel: The fitted generalised linear model of the GLM package.

Related

source
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 input re, unchanged.

Related

source
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

  1. Check that rd carries both matrices, as # Validation states.
  2. Read the source of re with returns_source, and call it x_src. A regression that reads the returns data itself states its source in its x_src field.
  3. With shared_series_fit, drop the observations at which a factor return is not finite. Under x_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 of re loses the same observations.
  4. Read the asset returns with benchmark_relative_returns under x_src, and call them X. X is rd.X, or rd.X - rd.B under ExcessSource().
  5. 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 returns X and the factor returns F.

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. So x_src = PriorSource() throws an ArgumentError, because the call gives no Prior Result, and x_src = ExcessSource() refuses returns data with no benchmark.

Returns

  • reg::Regression: The fitted regression result.

Related

source
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

  1. Read L and b with getfield, never through property access. The swap(L, M) rule of Regression makes re.L return re.M when L is unset. So a property read puts a view of M in the L field of the new result, and the new result no longer shows that L was unset.
  2. Take a row view of M over i. These are the loadings of the selected assets.
  3. Take a row view of L over i when step 1 found a matrix, and nothing otherwise.
  4. Take an element view of b over i when step 1 found a vector, and nothing otherwise.
  5. View esigma with idiosyncratic_covariance_view, which reads its shape: a vector of variances is indexed once, and a full covariance is indexed on both axes.
  6. View edof and ediv with nothing_scalar_array_view, which indexes a vector once and passes nothing through.
  7. Build a new Regression from the six views and the unchanged row key idx and ts. 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 ┴ nothing

Related

source
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

  1. Read the weights with regression_target_weights. Return tgt when it holds none.
  2. Otherwise index them with obs_weights_index, and put them back with factory.

Arguments

Validation

Returns

  • tgt: The target with its weights at the kept observations.

Related

source

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).