Cross-Sectional Factor Model
Types
PortfolioOptimisers.CrossSectionalFactorModel — Type
struct CrossSectionalFactorModel{__T_M, __T_L, __T_b, __T_csr, __T_Ms, __T_vs, __T_esigma, __T_edof, __T_ediv, __T_rw, __T_bw, __T_nf, __T_fam, __T_fcb, __T_unseen, __T_lag, __T_rf, __T_fx, __T_fr, __T_lambda, __T_c, __T_idx, __T_ts, __T_amr, __T_hist} <: AbstractLoadingsRegressionResultHolds the loadings, the factor-orthogonal expected return and the fitted history of a factor model fitted per observation across the assets.
The result is the cross-sectional member of AbstractLoadingsRegressionResult, so a consumer that re-bases a constraint or decomposes risk in the factor basis reads it exactly as it reads a Regression. M carries the raw loadings, whose columns are the named original factors, because a constraint must be written in names a caller can put in an equation. Every field after b is optional, so a model that keeps its loadings and drops its histories is a member of the family, and a caller that asks for a dropped history reads nothing.
An unset L reads back as M. A @forward_properties swap(L, M) rule makes csfm.L return csfm.M whenever L was not given, as Regression behaves, so a consumer that decomposes risk in the factor basis needs no Nothing branch, and isnothing(csfm.L) is never true. Read getfield(csfm, :L) when the unset case must be told apart, as port_opt_view does.
Mathematical definition
\[\begin{align} \boldsymbol{x}_{t} &= b_{t} \boldsymbol{1} + \mathbf{M}_{t} \boldsymbol{f}_{t} + \boldsymbol{\varepsilon}_{t}\,, \\ \boldsymbol{\mu} &= \mathbf{M} \boldsymbol{\mu}_{f} + \boldsymbol{b}\,, \\ \mathbf{M} &= \mathbf{M}_{T}\,. \end{align}\]
Where:
- $\boldsymbol{x}_t$: Asset returns for observation $t$, the $t$-th row of the returns matrix.
- $b_{t}$: Intercept of observation $t$, the $t$-th entry of the intercept vector
CrossSectionalRegressioncarries. The term is absent when the fit carries no intercept. - $\boldsymbol{1}$: Vector of ones $N \times 1$.
- $\mathbf{M}_{t}$: Exposure slice of observation $t$, $N \times K$, the $t$-th slice of
Ms. - $\boldsymbol{f}_{t}$: Factor returns of observation $t$, on the axis of $\mathbf{M}_{t}$.
- $\boldsymbol{\varepsilon}_{t}$: Idiosyncratic returns of observation $t$, the part of $\boldsymbol{x}_{t}$ the exposures and the intercept do not explain.
- $\boldsymbol{\mu}$: Expected returns vector $N \times 1$.
- $\boldsymbol{\mu}_{f}$: Expected factor returns $K \times 1$. A factor prior carries it, and this result does not.
- $\boldsymbol{b}$: Factor-orthogonal expected return $N \times 1$,
b. It is the part of $\boldsymbol{\mu}$ the factors do not span, so it is a term of the expected return and never a term of one observation. - $\mathbf{M}$: Loadings matrix $N \times K$ of the factor model,
M. It is the last slice of the exposure history. - $N$: Number of assets.
- $K$: Number of factors.
- $T$: Number of observations.
Fields
M: Loadings matrixassets × factors. Its columns are the named original factors, so a constraint written in a factor's name resolves against it.
L: Loadings matrixassets × reduced_dimensionsin the reduced basis of a dimension reduction. It is set only after a family re-basis, and an unsetLreads back asM.
b: Factor-orthogonal expected return, one entry per asset. It is the part of the expected return the factors do not span, and it is not the per-observation intercept of the fit, whichcsrcarries.
csr: The cross-sectional fit the model was built around. It carries the factor returns, the idiosyncratic returns, the eligible asset counts and the per-observation intercepts.
Ms: Exposure historyassets × factors × observations. Its last slice is the loadings matrixM. The constructor checks the two axes it shares withMand never the entries, so a caller that builds both keeps them in step itself.
vs: Idiosyncratic variance historyobservations × assets. Rowtholds the variances estimated from the observations up tot.
esigma: Idiosyncratic covariance. A vector holds the variances alone, and a matrix holds the full covariance.
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: 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.
rw: Regression weight historyobservations × assets. Entry(t, i)is the weight asseticarried in the fit of observationt, and a weight of zero excluded the pair.
bw: Benchmark weight historyobservations × assets. Entry(t, i)is the weight asseticarried in the benchmark of observationt.
nf: Name of each raw factor, one entry per column ofM. The prior derives the axis from its Exposure Estimators and stores the answer here, so a consumer that names a factor reads one list.
fam: Family label of each raw factor, one entry per column ofM.
fcb: The family re-basisLis written in. It is present exactly whenLis present. Its rows are the rows ofMs, one basis for the exposures of each observation, and its last row re-basesMintoL. The factor return of rowtofcsr.fwas fitted on the exposures of rowt - lag, so it is written in the basis of rowt - lag: a transform of a factor-return history reads the basis rows1:(T - lag)against the return rows(1 + lag):T.
unseen: The Unseen Member rule the fit regressed under. A consumer that rebuilds the design of each observation, the regression diagnostics and the standard errors of afactor_attribution, callsunseen_member_designof the rule onMs,fcbandrw, so it reads the design that the fit regressed on. A block without a family re-basis has no Unseen Member, so the rule changes nothing there.
lag: Number of observations by which the exposures lag the returns.
rf: The Return Forecast the prior fitted, ornothing. Itsmuis the forecastbwas split out of, so a consumer reads the forecast the split consumed rather than refitting it.
fx: Returns of the observed factors,observations × factors, on the rows ofcsr.f, ornothingwhen the model has no observed factor. The fit observes them, for example the Currency Excess Returns of the Currency Factors, and does not estimate them, socsrdoes not carry them. The observed factors are the trailing columns of the raw axis and of the reduced axis, andcross_sectional_factor_returnsreads them besidecsr.f.
fr: Factor returns on the raw factor axis,observations × factors, on the rows ofcsr.fand with one column per column ofM, ornothing. A block with a family re-basis carries it, and a block with none leaves itnothing, because its raw axis is the axis ofcross_sectional_factor_returns. The fit states the factor returns in the reduced basis of rowt - lag, andfcbholds the basis of the rows of the block alone, so it cannot expand the firstlagrows. The prior expands every row with the basis of its own history, and a consumer that needs a dropped factor's return, for examplefactor_model_summaryandfactor_attribution, reads it here.
lambda: Spanned Shrinkage the prior resolved, ornothingwhen the block was not built by a prior. A rule in the slot and a stated number are recorded alike, so a caller reads back the number the mean used.
c: Orthogonal Forecast Scale the prior resolved, ornothingwhen the block was not built by a prior.bis this scale times the unscaled orthogonal part of the Return Forecast.
idx: Position of each row of the fit in the returns data that the prior read, ornothing. The fit drops the Descriptor warm-up and the exposure lag, so its first row is a later row of the data. Afactor_attributionof a cross-validation reads it to find the rows of the block that each fold covers. A prior folded online counts the positions over every observation it folded.
ts: Timestamp of each row of the fit, 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 rows.
amr: Active-mask historyobservations × assets, on the rows ofcsr.f, ornothing. Entry(t, i)is true where assetiwas active at the observation of rowt. A prior fitted withcache_reg = truestores it, so its refit under new scenario weights reads the active assets of the latest row from the block and runs no regression. Every other fit leaves itnothing.
hist: Return Forecast historyobservations × assets, on the rows ofcsr.f, ornothing. It is the history that a Calibration Slot of the prior read. A prior fitted withcache_reg = truestores it when a slot reads it, so its refit under new scenario weights resolves the slot again from the block. Every other fit leaves itnothing.
Constructors
CrossSectionalFactorModel(; M::MatNum, L::Option{<:MatNum} = nothing, b::VecNum, csr::Option{<:CrossSectionalRegression} = nothing, Ms::Option{<:Arr3Num} = nothing, vs::Option{<:MatNum} = nothing, esigma::Option{<:VecNum_MatNum} = nothing, edof::Option{<:VecNum} = nothing, ediv::Option{<:VecNum} = nothing, rw::Option{<:MatNum} = nothing, bw::Option{<:MatNum} = nothing, nf::Option{<:VecStr} = nothing, fam::Option{<:VecStr} = nothing, fcb::Option{<:AbstractFactorFamilyBasis} = nothing, unseen::AbstractUnseenMemberRule = SolvedUnseenMember(), lag::Option{<:Integer} = nothing, rf::Option{<:AbstractReturnForecastResult} = nothing, fx::Option{<:MatNum} = nothing, fr::Option{<:MatNum} = nothing, lambda::Option{<:Number} = nothing, c::Option{<:Number} = nothing, idx::Option{<:VecInt} = nothing, ts::Option{<:VecDate} = nothing, amr::Option{<:AbstractMatrix{Bool}} = nothing, hist::Option{<:MatNum} = nothing) -> CrossSectionalFactorModelKeywords correspond to the struct's fields.
Validation
!isempty(M),!isempty(b), andlength(b) == size(M, 1).Landfcbare present together, or absent together.- If provided,
!isempty(L), andsize(L, 1) == size(M, 1). - If provided,
!isempty(nf),length(nf) == size(M, 2), andnfrepeats no name. - If provided,
!isempty(fam), andlength(fam) == size(M, 2). - If provided,
!isempty(Ms),size(Ms, 1) == size(M, 1), andsize(Ms, 2) == size(M, 2). - If provided,
size(csr.eps, 2) == size(M, 1). - If provided,
!isempty(vs),!isempty(rw),!isempty(bw),!isempty(amr),!isempty(hist), and each carriessize(M, 1)columns. - Every two of
vs,rw,bw,amrandhistthat are present agree on the observation axis, sosize(rw) == size(bw) == size(vs)when all three are present. - 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. - If provided,
lag >= 0. - If provided,
length(rf.mu) == size(M, 1), andrf.histcarriessize(M, 1)columns when the member computes one. - If provided,
fxpassesassert_observed_factor_returns:csris given,fxhas the rows ofcsr.f, and the two fill the column count ofL(or ofMwhenLis unset). - If provided,
frneedsfcbandcsr, andsize(fr) == (size(csr.f, 1), size(M, 2)). - The rules of
assert_cs_block_rowsonidxandts.
View parameters
CrossSectionalFactorModel defines its own port_opt_view method rather than deriving one from field tags.
M,Landbare sliced on their first axis, which is the asset axis of a loadings result.csris viewed by its ownport_opt_viewmethod.Msis sliced on its first axis, which is the asset axis of a slice.vs,rw,bw,amrandhistare sliced on their second axis, which is the asset axis of a per-asset history.esigmais sliced byidiosyncratic_covariance_view, on one axis or on both.edofandedivare sliced on their only axis, which is the asset axis.rfis viewed by its ownport_opt_viewmethod, which cutsmuandhiston the asset axis.nf,fam,fcb,unseen,lag,fx,fr,lambda,c,idxandtspass through unchanged. Each is indexed by factor, by observation, or by nothing at all, and none follows an asset selection.
Examples
julia> CrossSectionalFactorModel(; M = [1.0 2.0; 3.0 4.0; 5.0 6.0], b = [0.1, 0.2, 0.3], esigma = [0.4, 0.5, 0.6], fam = ["style", "style"], lag = 1)CrossSectionalFactorModel M ┼ 3×2 Matrix{Float64} L ┼ 3×2 Matrix{Float64} b ┼ Vector{Float64}: [0.1, 0.2, 0.3] csr ┼ nothing Ms ┼ nothing vs ┼ nothing esigma ┼ Vector{Float64}: [0.4, 0.5, 0.6] edof ┼ nothing ediv ┼ nothing rw ┼ nothing bw ┼ nothing nf ┼ nothing fam ┼ Vector{String}: ["style", "style"] fcb ┼ nothing unseen ┼ SolvedUnseenMember() lag ┼ Int64: 1 rf ┼ nothing fx ┼ nothing fr ┼ nothing lambda ┼ nothing c ┼ nothing idx ┼ nothing ts ┼ nothing amr ┼ nothing hist ┴ nothingRelated
PortfolioOptimisers.FactorDiagnosticResult — Type
struct FactorDiagnosticResult{__T_X, __T_nf, __T_fam, __T_dims} <: AbstractResultHolds the answer of a Factor Model Diagnostic together with the names and the family labels of its factor axis.
A diagnostic verb called on a CrossSectionalFactorModel returns it. The method of the same verb over bare histories returns the bare array, because it has no names to carry. port_opt_view selects factors of the answer by position, by name, or by family with a LabelGroup. It cuts every factor dimension of X, and nf and fam with it. So a caller computes a diagnostic once, over every factor, and then selects the factors it reads.
Fields
X: The answer of the diagnostic: a vector with one entry per factor, a matrixobservations × factors, or a matrixfactors × factors.
nf: Name of each factor on the factor axis of the answer, ornothingwhen the block names no factor. The axis is the one that the verb answers on, raw or reduced.
fam: Family label of each factor on the factor axis of the answer, ornothingwhen the block labels no family. A view selects the factors of one family with aLabelGroup.
dims: The dimensions ofXthat run over the factors:(ndims(X),)for a series of the factors, and(1, 2)for a matrix of factor pairs.
Constructors
FactorDiagnosticResult(; X::AbstractArray, nf::Option{<:VecStr} = nothing, fam::Option{<:VecStr} = nothing, dims::Tuple{Vararg{Integer}} = (ndims(X),)) -> FactorDiagnosticResultKeywords correspond to the struct's fields.
Validation
!isempty(dims), anddimsnames distinct dimensions ofX. Raises aDomainErrorotherwise.- Every dimension of
Xthatdimsnames has one length, the factor countK. Raises aDimensionMismatchotherwise. - If provided,
length(nf) == K, andnfrepeats no name. - If provided,
length(fam) == K.
Examples
julia> r = FactorDiagnosticResult(; X = [1.0 2.0 3.0; 4.0 5.0 6.0], nf = ["value", "size", "tech"], fam = ["style", "style", "industry"]);julia> PortfolioOptimisers.port_opt_view(r, LabelGroup("style")).X2×2 view(::Matrix{Float64}, :, [1, 2]) with eltype Float64: 1.0 2.0 4.0 5.0julia> PortfolioOptimisers.port_opt_view(r, ["tech"]).nf1-element view(::Vector{String}, [3]) with eltype String: "tech"Related
Functions
PortfolioOptimisers.port_opt_view — Method
port_opt_view(csfm::CrossSectionalFactorModel, i, args...)Return a view of a CrossSectionalFactorModel result, selecting only the assets indexed by i.
Algorithm
- Read
Lwithgetfield, never through property access. Theswap(L, M)rule ofCrossSectionalFactorModelmakescsfm.Lreturncsfm.MwhenLis unset, so a property read would materialiseLas a copy ofMand lose the unset-ness. - Take a row view of
M, ofLwhen step 1 found a matrix, and an element view ofb, giving the loadings and the factor-orthogonal expected return of the selected assets. - View the nested fit with its own
port_opt_viewmethod, which cuts its residuals on the asset axis. - Take a view of
Mson its first axis, and ofvs,rw,bw,amrandhiston their second axis, giving the histories of the selected assets. - View
esigmawithidiosyncratic_covariance_view, which reads its shape, and viewedofandedivwithnothing_scalar_array_view. - View the Return Forecast with its own
port_opt_viewmethod, which cutsmuandhiston the asset axis. - Build a new
CrossSectionalFactorModelfrom the views, passingnf,fam,fcb,lag,fx,fr,lambda,c,idxandtsthrough, which re-runs every guard of the constructor.
Arguments
csfm: A cross-sectional factor model result.i: Indices of the assets to select.args...: Additional positional arguments (ignored).
Returns
csfm::CrossSectionalFactorModel: A new result whose per-asset fields are restricted to the selected assets.
Examples
julia> csfm = CrossSectionalFactorModel(; M = [1.0 2.0; 3.0 4.0; 5.0 6.0], b = [0.1, 0.2, 0.3], esigma = [0.4, 0.5, 0.6]);julia> PortfolioOptimisers.port_opt_view(csfm, [1, 3]).b2-element view(::Vector{Float64}, [1, 3]) with eltype Float64: 0.1 0.3julia> isnothing(getfield(PortfolioOptimisers.port_opt_view(csfm, [1, 3]), :L))trueRelated
PortfolioOptimisers.regression — Method
regression(csfm::CrossSectionalFactorModel, args...)Return the cross-sectional factor model unchanged.
This method is a pass-through for CrossSectionalFactorModel results, as the method over Regression is for that result. A consumer that binds RegE_Reg takes either a result or an estimator, and calls regression on both.
Arguments
csfm: A cross-sectional factor model result.args...: Additional arguments (ignored).
Returns
- The input
csfm, unchanged.
Related
PortfolioOptimisers.cross_sectional_factor_returns — Function
cross_sectional_factor_returns(csfm::CrossSectionalFactorModel) -> MatNumReturn the factor returns of a CrossSectionalFactorModel on the axis of its loadings L: the factors the fit estimated, then the observed factors.
The fit estimates csr.f on its own design axis, which is the reduced axis less the observed factors, and it observes the returns fx. The two side by side are the factor returns that the loadings L (or M when the model has no family re-basis) multiply. So the loadings of observation t - lag times row t of the answer, plus the idiosyncratic return of t, give the returns of observation t in the base currency.
Algorithm
- Refuse a block that carries no fit.
- Return
csr.fwhenfxisnothing, andhcat(csr.f, fx)otherwise.
Arguments
csfm: A cross-sectional factor model block.
Validation
csfm.csris notnothing. Raises anIsNothingError.
Returns
f::MatNum: The factor returns,observations × factors, on the axis ofL.
Related
PortfolioOptimisers.port_opt_view — Method
port_opt_view(r::FactorDiagnosticResult, i, args...)Return a view of a FactorDiagnosticResult that keeps only the factors that i selects.
Algorithm
- Turn
iinto positions on the factor axis withfactor_axis_positions. - View
Xat those positions on each dimension thatdimsnames, and in full on each other dimension. - View
nfandfamat those positions withnothing_scalar_array_view. - Build a new
FactorDiagnosticResultfrom the views, which runs the guards of the constructor again.
Arguments
r: A diagnostic answer.i: The factor index: positions, a range, aColon, a vector of names, or aLabelGroup.args...: Additional positional arguments (ignored).
Validation
- The rules of
factor_axis_positions.
Returns
r::FactorDiagnosticResult: The answer on the selected factors.
Examples
julia> r = FactorDiagnosticResult(; X = [1.0 0.5; 0.5 1.0], nf = ["value", "size"], dims = (1, 2));julia> PortfolioOptimisers.port_opt_view(r, 2).X1×1 view(::Matrix{Float64}, 2:2, 2:2) with eltype Float64: 1.0Related
PortfolioOptimisers.cs_diagnostic_factor_names — Function
cs_diagnostic_factor_names(csfm::CrossSectionalFactorModel)
cs_diagnostic_factor_names(fcb::Option{<:AbstractFactorFamilyBasis}, nf::Nothing)
cs_diagnostic_factor_names(fcb::Nothing, nf::VecStr)
cs_diagnostic_factor_names(fcb::AbstractFactorFamilyBasis, nf::VecStr)Return the factor names of the axis a cross-sectional regression diagnostic answers on.
A regression diagnostic that carries a factor axis answers on the design of the regression: the reduced axis when the block carries a family re-basis, less the observed factors, which are its last columns and which the regression did not estimate. So the names of the raw axis do not label it. The one-argument verb maps them, and the FactorDiagnosticResult of a regression diagnostic carries its answer. The two-argument verb maps the names onto the whole reduced axis, observed factors included, which is the axis of the loadings L. It maps family labels the same way. A block that names no factor answers nothing.
Arguments
csfm: A cross-sectional factor model block.fcb: The family re-basis of the block, ornothing.nf: The names, or the family labels, of the raw factor axis, ornothing.
Returns
nf::Option{<:Vector{String}}: The names of the answer's factor axis, ornothingwhen the block names no factor.
Examples
julia> csfm = CrossSectionalFactorModel(; M = [1.0 2.0; 3.0 4.0], b = [0.1, 0.2], esigma = [0.4, 0.5], nf = ["value", "size"]);julia> PortfolioOptimisers.cs_diagnostic_factor_names(csfm)2-element Vector{String}: "value" "size"Related