Factor Family Basis Transforms: private API

Functions

PortfolioOptimisers.reduce_factor_names — Function

reduce_factor_names(
    fcb::FactorFamilyBasis,
    nf::AbstractVector{<:AbstractString}
) -> Vector{String}

Return the names of the reduced factor axis.

The reduced axis follows the raw order with the dropped factor of every constrained family removed, so a retained factor keeps its raw name and its economic meaning.

Arguments

fcb: A Factor Family Basis.
nf::VecStr: Names of the raw factor axis, of length fcb.K.

Validation

length(nf) == fcb.K.

Returns

nf::Vector{String}: The retained names, in reduced-axis order.

Examples

julia> fcb = FactorFamilyBasis(; fnm = ["ind"], fi = [[2, 3]], di = [2],                               ratios = reshape([0.5], 1, 1), K = 3);julia> PortfolioOptimisers.reduce_factor_names(fcb, ["mkt", "ind=a", "ind=b"])2-element Vector{String}: "mkt" "ind=a"

Related

source

PortfolioOptimisers.reduce_exposures — Function

reduce_exposures(
    fcb::FactorFamilyBasis,
    Ms::AbstractArray{<:Union{var"#s136", var"#s53"} where {var"#s136"<:Number, var"#s53"<:AbstractJuMPScalar}, 3}
) -> Array{_A, 3} where _A

Map an exposure history onto the reduced factor axis.

Mathematical definition

For a family that drops member $k$, each retained member $j$ becomes

\[z_{t,j} = x_{t,j} - \frac{c_t(j)}{c_t(k)} \, x_{t,k},\]

and a factor outside every constrained family is copied unchanged.

Where:

$x_{t,j}$: raw exposure of the assets to factor $j$ at observation $t$.
$c_t(j) / c_t(k)$: the entry of fcb.ratios for member $j$.

Arguments

fcb: A Factor Family Basis.
Ms::Arr3Num: Exposure history on the raw axis, observations × assets × factors.

Validation

size(Ms, 3) == fcb.K, and size(Ms, 1) matches the observation axis of the basis.

Returns

Ms::Array{<:Real, 3}: The exposure history on the reduced axis, observations × assets × reduced factors.

Related

source

PortfolioOptimisers.reduce_loadings — Function

reduce_loadings(fcb::FactorFamilyBasis, M::MatNum, t::Integer = size(fcb.ratios, 1))

Map a point-in-time loading matrix onto the reduced factor axis.

This is reduce_exposures at one observation, so it applies the ratios of observation t to a matrix of assets by raw factors.

Arguments

fcb: A Factor Family Basis.
M::MatNum: Loading matrix on the raw axis, assets × factors.
t::Integer: Observation whose ratios are applied. It defaults to the last observation of the basis.

Validation

size(M, 2) == fcb.K, and t indexes the observation axis of the basis.

Returns

L::Matrix{<:Real}: The loading matrix on the reduced axis, assets × reduced factors.

Related

source

PortfolioOptimisers.reduce_factor_returns — Function

reduce_factor_returns(
    fcb::FactorFamilyBasis,
    f::AbstractMatrix{<:Union{var"#s136", var"#s53"} where {var"#s136"<:Number, var"#s53"<:AbstractJuMPScalar}}
) -> Any

Drop the redundant factor returns, giving the reduced-axis factor returns.

Factor returns are coordinates in factor-return space, so the reduction keeps the retained columns and applies no ratio. It is the inverse of expand_factor_returns.

Arguments

fcb: A Factor Family Basis.
f::VecNum_MatNum: Factor returns on the raw axis, either one observation per row or one observation alone.

Validation

The factor axis of f is fcb.K.

Returns

f::Array{<:Real}: The factor returns on the reduced axis, of the same number of dimensions as the input.

Related

source

PortfolioOptimisers.reduce_factor_mu — Function

reduce_factor_mu(
    fcb::FactorFamilyBasis,
    mu::AbstractVector{<:Union{var"#s136", var"#s53"} where {var"#s136"<:Number, var"#s53"<:AbstractJuMPScalar}}
) -> Any

Drop the redundant entries of a factor mean, giving the reduced-axis mean.

It is the inverse of expand_factor_mu, and it applies no ratio.

Arguments

fcb: A Factor Family Basis.
mu::VecNum: Factor mean on the raw axis.

Validation

length(mu) == fcb.K.

Returns

mu::Vector{<:Real}: The factor mean on the reduced axis.

Related

source

PortfolioOptimisers.reduce_factor_covariance — Function

reduce_factor_covariance(
    fcb::FactorFamilyBasis,
    sigma::AbstractMatrix{<:Union{var"#s136", var"#s53"} where {var"#s136"<:Number, var"#s53"<:AbstractJuMPScalar}}
) -> Any

Take the full-rank block of a factor covariance, giving the reduced-axis covariance.

The reduced factor returns are the retained raw ones, so the reduced covariance is the submatrix of the retained indices and no ratio is applied. It is the inverse of expand_factor_covariance.

Arguments

fcb: A Factor Family Basis.
sigma::MatNum: Factor covariance on the raw axis, factors × factors.

Validation

size(sigma) == (fcb.K, fcb.K).

Returns

sigma::Matrix{<:Real}: The factor covariance on the reduced axis.

Related

source

PortfolioOptimisers.expand_factor_returns — Function

expand_factor_returns(
    fcb::FactorFamilyBasis,
    g::AbstractMatrix{<:Union{var"#s136", var"#s53"} where {var"#s136"<:Number, var"#s53"<:AbstractJuMPScalar}}
) -> Any

Reconstruct the raw-axis factor returns from the reduced-axis ones.

Mathematical definition

The retained returns pass through, and the dropped return of each family follows from the zero-sum condition:

\[f_k(t) = -\sum_{j \ne k} \frac{c_t(j)}{c_t(k)} \, g_j(t).\]

Where:

$g_j(t)$: reduced-axis factor return of retained member $j$ at observation $t$.
$f_k(t)$: raw-axis factor return of the dropped member $k$.

Arguments

fcb: A Factor Family Basis.
g::VecNum_MatNum: Factor returns on the reduced axis. A matrix carries one observation per row and expands each row with that row's ratios. A vector expands with the ratios of the last observation.

Validation

The factor axis of g is the reduced factor count, and a matrix matches the observation axis of the basis.

Returns

f::Array{<:Real}: The factor returns on the raw axis, of the same number of dimensions as the input.

Related

source

PortfolioOptimisers.expand_factor_mu — Function

expand_factor_mu(fcb::FactorFamilyBasis, mu::VecNum, t::Integer = size(fcb.ratios, 1))

Reconstruct the raw-axis factor mean from the reduced-axis one.

The retained entries pass through, and the dropped entry of each family is the zero-sum reconstruction at observation t. It is the inverse of reduce_factor_mu.

Arguments

fcb: A Factor Family Basis.
mu::VecNum: Factor mean on the reduced axis.
t::Integer: Observation whose ratios are applied. It defaults to the last observation of the basis.

Validation

length(mu) is the reduced factor count, and t indexes the observation axis of the basis.

Returns

mu::Vector{<:Real}: The factor mean on the raw axis.

Related

source

PortfolioOptimisers.expand_factor_covariance — Function

expand_factor_covariance(fcb::FactorFamilyBasis, sigma::MatNum,
                         t::Integer = size(fcb.ratios, 1))

Reconstruct the raw-axis factor covariance from the reduced-axis one.

Mathematical definition

\[\Sigma = R_t \, \Sigma^{\mathrm{red}} \, R_t^{\top}.\]

Where:

$R_t$: the change of basis at observation $t$, which is never formed. The retained block is copied, and the dropped rows and columns come from the reconstruction weights of dropped_factor_weights.

The answer is singular by construction, because the raw axis is a linear image of a smaller one.

Arguments

fcb: A Factor Family Basis.
sigma::MatNum: Factor covariance on the reduced axis, reduced factors × reduced factors.
t::Integer: Observation whose ratios are applied. It defaults to the last observation of the basis.

Validation

size(sigma) is the reduced factor count on both axes, and t indexes the observation axis of the basis.

Returns

sigma::Matrix{<:Real}: The factor covariance on the raw axis.

Related

FactorFamilyBasis
reduce_factor_covariance
dropped_factor_weights

source

PortfolioOptimisers.project_factor_coordinates — Function

project_factor_coordinates(
    fcb::FactorFamilyBasis,
    x::AbstractMatrix{<:Union{var"#s136", var"#s53"} where {var"#s136"<:Number, var"#s53"<:AbstractJuMPScalar}}
) -> Matrix

Project raw factor-space coordinates into the reduced basis.

This applies the transpose of the change of basis, so it is not a column selection: the coordinate of a dropped factor contributes to the retained coordinates of its family. A portfolio's factor exposure is such a coordinate.

Mathematical definition

\[y_j = x_j - \frac{c_t(j)}{c_t(k)} \, x_k, \qquad j \ne k.\]

Where:

$x_j$: raw coordinate of retained member $j$.
$x_k$: raw coordinate of the dropped member $k$.

Arguments

fcb: A Factor Family Basis.
x::VecNum_MatNum: Coordinates on the raw axis. A matrix carries one observation per row and projects each row with that row's ratios. A vector projects with the ratios of the last observation.

Validation

The factor axis of x is fcb.K, and a matrix matches the observation axis of the basis.

Returns

y::Array{<:Real}: The coordinates on the reduced axis, of the same number of dimensions as the input.

Related

source

PortfolioOptimisers.dropped_factor_weights — Function

dropped_factor_weights(
    fcb::FactorFamilyBasis,
    t::Integer
) -> Any

Return the reduced-axis weights that reconstruct the dropped factors at one observation.

Row j holds the coefficients of the zero-sum condition of family j, so the dropped factor of that family is the row applied to a reduced-axis quantity. The dense change of basis is never formed.

Arguments

fcb: A Factor Family Basis.
t::Integer: Observation whose ratios are read.

Validation

t indexes the observation axis of the basis.

Returns

W::Matrix{<:Real}: The reconstruction weights, constrained families × reduced factors.

Related

source

PortfolioOptimisers.assert_factor_basis_index — Function

assert_factor_basis_index(
    t::Integer,
    fcb::FactorFamilyBasis
)

Refuse an observation index that does not lie on the observation axis of the basis.

Arguments

t::Integer: Observation index.
fcb: A Factor Family Basis.

Validation

1 <= t <= size(fcb.ratios, 1).

Returns

nothing.

Related

FactorFamilyBasis

source