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} <: AbstractLoadingsRegressionResult

Holds 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 CrossSectionalRegression carries. 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 matrix assets × factors. Its columns are the named original factors, so a constraint written in a factor's name resolves against it.
  • L: Loadings matrix assets × reduced_dimensions in the reduced basis of a dimension reduction. It is set only after a family re-basis, and an unset L reads back as M.
  • 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, which csr carries.
  • 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 history assets × factors × observations. Its last slice is the loadings matrix M. The constructor checks the two axes it shares with M and never the entries, so a caller that builds both keeps them in step itself.
  • vs: Idiosyncratic variance history observations × assets. Row t holds the variances estimated from the observations up to t.
  • 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 writes esigma restates it in the count of its variance estimator.
  • 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.
  • rw: Regression weight history observations × assets. Entry (t, i) is the weight asset i carried in the fit of observation t, and a weight of zero excluded the pair.
  • bw: Benchmark weight history observations × assets. Entry (t, i) is the weight asset i carried in the benchmark of observation t.
  • nf: Name of each raw factor, one entry per column of M. 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 of M.
  • fcb: The family re-basis L is written in. It is present exactly when L is present. Its rows are the rows of Ms, one basis for the exposures of each observation, and its last row re-bases M into L. The factor return of row t of csr.f was fitted on the exposures of row t - lag, so it is written in the basis of row t - lag: a transform of a factor-return history reads the basis rows 1:(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 a factor_attribution, calls unseen_member_design of the rule on Ms, fcb and rw, 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, or nothing. Its mu is the forecast b was 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 of csr.f, or nothing when 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, so csr does not carry them. The observed factors are the trailing columns of the raw axis and of the reduced axis, and cross_sectional_factor_returns reads them beside csr.f.
  • fr: Factor returns on the raw factor axis, observations × factors, on the rows of csr.f and with one column per column of M, or nothing. A block with a family re-basis carries it, and a block with none leaves it nothing, because its raw axis is the axis of cross_sectional_factor_returns. The fit states the factor returns in the reduced basis of row t - lag, and fcb holds the basis of the rows of the block alone, so it cannot expand the first lag rows. The prior expands every row with the basis of its own history, and a consumer that needs a dropped factor's return, for example factor_model_summary and factor_attribution, reads it here.
  • lambda: Spanned Shrinkage the prior resolved, or nothing when 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, or nothing when the block was not built by a prior. b is 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, or nothing. The fit drops the Descriptor warm-up and the exposure lag, so its first row is a later row of the data. A factor_attribution of 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, 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 rows.
  • amr: Active-mask history observations × assets, on the rows of csr.f, or nothing. Entry (t, i) is true where asset i was active at the observation of row t. A prior fitted with cache_reg = true stores 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 it nothing.
  • hist: Return Forecast history observations × assets, on the rows of csr.f, or nothing. It is the history that a Calibration Slot of the prior read. A prior fitted with cache_reg = true stores it when a slot reads it, so its refit under new scenario weights resolves the slot again from the block. Every other fit leaves it nothing.

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

Keywords correspond to the struct's fields.

Validation

  • !isempty(M), !isempty(b), and length(b) == size(M, 1).
  • L and fcb are present together, or absent together.
  • If provided, !isempty(L), and size(L, 1) == size(M, 1).
  • If provided, !isempty(nf), length(nf) == size(M, 2), and nf repeats no name.
  • If provided, !isempty(fam), and length(fam) == size(M, 2).
  • If provided, !isempty(Ms), size(Ms, 1) == size(M, 1), and size(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 carries size(M, 1) columns.
  • Every two of vs, rw, bw, amr and hist that are present agree on the observation axis, so size(rw) == size(bw) == size(vs) when all three are present.
  • 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.
  • If provided, lag >= 0.
  • If provided, length(rf.mu) == size(M, 1), and rf.hist carries size(M, 1) columns when the member computes one.
  • If provided, fx passes assert_observed_factor_returns: csr is given, fx has the rows of csr.f, and the two fill the column count of L (or of M when L is unset).
  • If provided, fr needs fcb and csr, and size(fr) == (size(csr.f, 1), size(M, 2)).
  • The rules of assert_cs_block_rows on idx and ts.

View parameters

CrossSectionalFactorModel defines its own port_opt_view method rather than deriving one from field tags.

  • M, L and b are sliced on their first axis, which is the asset axis of a loadings result.
  • csr is viewed by its own port_opt_view method.
  • Ms is sliced on its first axis, which is the asset axis of a slice.
  • vs, rw, bw, amr and hist are sliced on their second axis, which is the asset axis of a per-asset history.
  • esigma is sliced by idiosyncratic_covariance_view, on one axis or on both.
  • edof and ediv are sliced on their only axis, which is the asset axis.
  • rf is viewed by its own port_opt_view method, which cuts mu and hist on the asset axis.
  • nf, fam, fcb, unseen, lag, fx, fr, lambda, c, idx and ts pass 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 ┴ nothing

Related

source
PortfolioOptimisers.FactorDiagnosticResult — Type
struct FactorDiagnosticResult{__T_X, __T_nf, __T_fam, __T_dims} <: AbstractResult

Holds 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 matrix observations × factors, or a matrix factors × factors.
  • nf: Name of each factor on the factor axis of the answer, or nothing when 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, or nothing when the block labels no family. A view selects the factors of one family with a LabelGroup.
  • dims: The dimensions of X that 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),)) -> FactorDiagnosticResult

Keywords correspond to the struct's fields.

Validation

  • !isempty(dims), and dims names distinct dimensions of X. Raises a DomainError otherwise.
  • Every dimension of X that dims names has one length, the factor count K. Raises a DimensionMismatch otherwise.
  • If provided, length(nf) == K, and nf repeats 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

source

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

  1. Read L with getfield, never through property access. The swap(L, M) rule of CrossSectionalFactorModel makes csfm.L return csfm.M when L is unset, so a property read would materialise L as a copy of M and lose the unset-ness.
  2. Take a row view of M, of L when step 1 found a matrix, and an element view of b, giving the loadings and the factor-orthogonal expected return of the selected assets.
  3. View the nested fit with its own port_opt_view method, which cuts its residuals on the asset axis.
  4. Take a view of Ms on its first axis, and of vs, rw, bw, amr and hist on their second axis, giving the histories of the selected assets.
  5. View esigma with idiosyncratic_covariance_view, which reads its shape, and view edof and ediv with nothing_scalar_array_view.
  6. View the Return Forecast with its own port_opt_view method, which cuts mu and hist on the asset axis.
  7. Build a new CrossSectionalFactorModel from the views, passing nf, fam, fcb, lag, fx, fr, lambda, c, idx and ts through, 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))true

Related

source
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

source
PortfolioOptimisers.cross_sectional_factor_returns — Function
cross_sectional_factor_returns(csfm::CrossSectionalFactorModel) -> MatNum

Return 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

  1. Refuse a block that carries no fit.
  2. Return csr.f when fx is nothing, and hcat(csr.f, fx) otherwise.

Arguments

  • csfm: A cross-sectional factor model block.

Validation

Returns

  • f::MatNum: The factor returns, observations × factors, on the axis of L.

Related

source
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

  1. Turn i into positions on the factor axis with factor_axis_positions.
  2. View X at those positions on each dimension that dims names, and in full on each other dimension.
  3. View nf and fam at those positions with nothing_scalar_array_view.
  4. Build a new FactorDiagnosticResult from the views, which runs the guards of the constructor again.

Arguments

  • r: A diagnostic answer.
  • i: The factor index: positions, a range, a Colon, a vector of names, or a LabelGroup.
  • args...: Additional positional arguments (ignored).

Validation

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

Related

source
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, or nothing.
  • nf: The names, or the family labels, of the raw factor axis, or nothing.

Returns

  • nf::Option{<:Vector{String}}: The names of the answer's factor axis, or nothing when 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

source