Cross-Sectional Exposure Diagnostics: private API
Types
PortfolioOptimisers.ExposurePairSums — Type
struct ExposurePairSums{__T_nv, __T_W, __T_Sk, __T_Sl, __T_Qk, __T_Ql, __T_C}The weighted sums of one pair of factor exposures over the assets that they share at one observation.
This type is an implementation detail and is not intended for direct use. exposure_pair_sums makes it. exposure_pair_observation reads it.
Fields
nv:nv: The count of the shared assets.
W:W: The sum of the weights.
Sk:Sk: The weighted sum of the first exposure.
Sl:Sl: The weighted sum of the second exposure.
Qk:Qk: The weighted sum of the squares of the first exposure.
Ql:Ql: The weighted sum of the squares of the second exposure.
C:C: The weighted sum of the products of the two exposures.
Related
Functions
PortfolioOptimisers.exposure_weights — Function
exposure_weights(B::Arr3Num, w::Nothing)
exposure_weights(B::Arr3Num, w::MatNum)Return the cross-sectional weight history an exposure diagnostic reads, checking it against the exposure history.
Every diagnostic of this file weights the assets of one observation, and an absent weight history means equal weights. The function resolves the absent case once, into a history of ones, so each kernel reads one matrix and no kernel carries a branch. An asset enters a diagnostic only where its weight is finite and positive, so a weight of zero, a NaN or an infinite weight excludes the asset from that observation.
Arguments
B: Exposure historyassets × factors × observations, unlagged.w: Cross-sectional weight historyobservations × assets, ornothingfor equal weights.
Validation
!isempty(B).size(w) == (size(B, 3), size(B, 1)), whenwis present.- No finite entry of
wis negative.
Returns
u::MatNum: Weight historyobservations × assets. It is a history of ones whenwisnothing, andwitself otherwise.
Related
PortfolioOptimisers.cs_weighted_correlation — Function
cs_weighted_correlation(a::AbstractVector, b::AbstractVector, u::AbstractVector;
min_count::Integer = 3, eps::Real = 1e-12)Return the weighted correlation of two cross-sections of one observation.
The information coefficient of an exposure against the forward return and the stability of an exposure against its own later self both call this kernel. An asset enters when both of its values are finite and its weight is finite and positive, so a missing value costs the pair alone and not the observation. A cross-section that is constant in one of the two values has no correlation, and the answer there is NaN.
Mathematical definition
\[\begin{align} \rho &= \frac{\sum_{i \in \mathcal{E}} u_{i} (a_{i} - \bar{a}) (b_{i} - \bar{b})}{\sqrt{\sum_{i \in \mathcal{E}} u_{i} (a_{i} - \bar{a})^{2}} \sqrt{\sum_{i \in \mathcal{E}} u_{i} (b_{i} - \bar{b})^{2}}}\,, \\ \bar{a} &= \frac{\sum_{i \in \mathcal{E}} u_{i} a_{i}}{\sum_{i \in \mathcal{E}} u_{i}}\,. \end{align}\]
Where:
- $a_{i}$, $b_{i}$: The two values of asset $i$.
- $u_{i}$: Weight of asset $i$.
- $\mathcal{E}$: The assets at which both values are finite and the weight is finite and positive.
- $\bar{a}$: Weighted mean of the first cross-section. $\bar{b}$ is the weighted mean of the second.
Algorithm
- Count the assets that enter into
n. Accumulate the weight sumws, the two weighted sumssaandsb, and the least and greatest value of each cross-section,loandhi, over them. - Answer
NaNwhen fewer thanmin_countassets enter, or when the weight sum is zero. - Clamp each weighted mean,
maandmb, to the range of its cross-section. The mean of equal values rounds, and the clamp makes the mean of a constant cross-section its common value exactly. - Accumulate the weighted central moments
cab,caaandcbbover the same assets. - Answer
NaNwhen the denominatordenis at or undereps. A cross-section that is constant in one of the two values has zero deviations, so its denominator is zero.
Arguments
a: First cross-section, one entry per asset.b: Second cross-section, one entry per asset.u: Weight of each asset. An entry that is not finite, or not positive, excludes the asset.min_count: Least number of assets an answer needs.eps: Denominator at or under which the answer isNaN.
Returns
rho::Real: The correlation, orNaN.
Examples
julia> PortfolioOptimisers.cs_weighted_correlation([1.0, 2.0, 3.0], [2.0, 4.0, 6.0], ones(3))1.0Related
PortfolioOptimisers.cs_correlation_enters — Function
cs_correlation_enters(a::AbstractVector, b::AbstractVector, u::AbstractVector,
i::Integer)Return whether one asset enters the correlation of two cross-sections.
An asset enters when both of its values are finite and its weight is finite and positive. The two passes of cs_weighted_correlation read the same rule, so the rule has one home.
Arguments
a: First cross-section, one entry per asset.b: Second cross-section, one entry per asset.u: Weight of each asset.i: Position of the asset.
Returns
enters::Bool:truewhen the asset enters.
Related
PortfolioOptimisers.cs_ranks — Function
cs_ranks(key::AbstractVector, valid::AbstractVector{Bool}, ties::Symbol)Return the rank of every entry of a cross-section, and NaN outside a mask.
The rank is the position the entry takes in the sorted order. ties sets the rank of equal values. :average gives each value of a tie the mean of the positions the tie takes, so the ranks do not read the order of the assets. :ordinal gives the values of a tie consecutive positions, in the order of the asset axis, which the stable sort keeps. The masked entries sort to the end by their key, and the function writes them as NaN, so they take no rank and shift none.
Mathematical definition
\[\begin{align} r_{i} &= \begin{cases} k_{i} + \dfrac{m_{i} + 1}{2} & \texttt{:average}\,, \\ \pi_{i} & \texttt{:ordinal}\,. \end{cases} \end{align}\]
Where:
- $r_{i}$: Rank of asset $i$.
- $k_{i}$: Number of assets in the mask whose key is below the key of asset $i$.
- $m_{i}$: Number of assets in the mask whose key equals the key of asset $i$, asset $i$ included.
- $\pi_{i}$: Position of asset $i$ in the stable sort of the keys.
Algorithm
- Sort the positions of
keywith a stable sort, givingp. - Walk
pin runs. Under:average, a run holds every entry of one key. Under:ordinal, a run holds one entry. - Write the mean position of the run to each entry of the run that is in the mask. Leave
NaNat each entry outside it.
Arguments
key: Sort key of each asset. The key of a masked asset must beInf, so the mask sorts to the end.valid: Mask, one entry per asset. Afalseentry getsNaN.ties: Rule that ranks the equal values of a cross-section.:averagegives each value of a tie the mean of the positions the tie takes, so a rank correlation does not read the order of the assets, and a constant cross-section has no rank correlation.:ordinalgives the values of a tie consecutive positions, in the order of the asset axis. The two rules give the same ranks to a cross-section with no tie.
Validation
tiesis:averageor:ordinal. Raises aConflictingArgumentError.
Returns
r::VecNum: Rank of each asset, orNaNoutside the mask.
Examples
julia> PortfolioOptimisers.cs_ranks([3.0, 1.0, 1.0, 2.0], trues(4), :average)4-element Vector{Float64}: 4.0 1.5 1.5 3.0julia> PortfolioOptimisers.cs_ranks([3.0, 1.0, 1.0, 2.0], trues(4), :ordinal)4-element Vector{Float64}: 4.0 1.0 2.0 3.0Related
PortfolioOptimisers.cs_spearman_correlation — Function
cs_spearman_correlation(a::AbstractVector, b::AbstractVector;
min_count::Integer = 3, eps::Real = 1e-12,
ties::Symbol = :average)Return the rank correlation of two cross-sections of one observation.
It is the unweighted correlation of the ranks of the two cross-sections, taken over the assets at which both values are finite. The rank measures the order of the assets and not their level, so one extreme value moves the answer no more than one ordinary value does.
Under the default ties = :average, a cross-section that is constant over those assets has constant ranks, so the answer is NaN, as it is for cs_weighted_correlation. Under ties = :ordinal, the order of the assets inside a tie sets part of the answer, and a constant cross-section can answer 1 or -1.
Mathematical definition
\[\begin{align} \rho_{S} &= \rho \left( \boldsymbol{r}(\boldsymbol{a}), \boldsymbol{r}(\boldsymbol{b}), \boldsymbol{1} \right)\,. \end{align}\]
Where:
- $\rho_{S}$: Cross-sectional rank correlation, over the assets at which both cross-sections are finite. Under the default
ties = :average, equal values share the mean of their ranks. Underties = :ordinal, they take consecutive ranks, in the order of the asset axis. - $\rho$: The weighted correlation of two cross-sections, over the assets at which both values are finite and the weight is finite and positive.
- $\boldsymbol{a}$, $\boldsymbol{b}$: The two cross-sections.
- $\boldsymbol{r}(\boldsymbol{x})$: Ranks of the cross-section $\boldsymbol{x}$ over the assets at which both cross-sections are finite, under the rule
tiesnames. - $\boldsymbol{1}$: Equal weights.
Algorithm
- Mark the assets at which both values are finite.
- Rank each cross-section over those assets with
cs_ranks. - Correlate the two rank vectors with
cs_weighted_correlationunder equal weights.
Arguments
a: First cross-section, one entry per asset.b: Second cross-section, one entry per asset.min_count: Least number of assets an answer needs.eps: Denominator at or under which the answer isNaN.ties: Rule that ranks the equal values of a cross-section.:averagegives each value of a tie the mean of the positions the tie takes, so a rank correlation does not read the order of the assets, and a constant cross-section has no rank correlation.:ordinalgives the values of a tie consecutive positions, in the order of the asset axis. The two rules give the same ranks to a cross-section with no tie.
Validation
- The rules of
cs_ranks.
Returns
rho::Real: The rank correlation, orNaN.
Examples
julia> a = [1.0, 1.0, 2.0, 2.0];julia> PortfolioOptimisers.cs_spearman_correlation(a, [1.0, 2.0, 3.0, 4.0]) ≈ 4 / sqrt(20)truejulia> PortfolioOptimisers.cs_spearman_correlation(a, [1.0, 2.0, 3.0, 4.0]; ties = :ordinal)1.0Related
PortfolioOptimisers.exposure_pair_correlation — Function
exposure_pair_correlation(B::Arr3Num, u::MatNum, k::Integer, l::Integer)Return the time-averaged correlation of one pair of factor exposures.
The verb correlates the pair at each observation, and averages the answers over the observations at which the pair has one. A pair that is degenerate at every observation it covers reads 0 by convention, and one that never reaches three common assets reads NaN.
Arguments
B: Exposure historyassets × factors × observations, unlagged.u: Resolved weight historyobservations × assets.k,l: Positions of the two factors.
Returns
rho::Real: The time-averaged correlation,0by convention, orNaN.
Related
PortfolioOptimisers.exposure_pair_observation — Function
exposure_pair_observation(B::Arr3Num, u::MatNum, t::Integer, k::Integer, l::Integer)Return the correlation of one pair of factor exposures at one observation, and whether the pair is degenerate there.
The correlation reads the assets at which both exposures are finite and the weight is finite and positive. It has no answer at an observation that shares fewer than three such assets, and none at one where either weighted variance falls to the tolerance of its own weighted square sum. The second case is degenerate, which the caller reads as the 0 convention, and the first is not.
Arguments
B: Exposure historyassets × factors × observations, unlagged.u: Resolved weight historyobservations × assets.t: Position of the observation.k,l: Positions of the two factors.
Returns
rho::Real: The correlation, orNaN.degenerate::Bool:truewhen the pair shares three assets and one of the two cross-sections is constant over them.
Related
PortfolioOptimisers.exposure_pair_sums — Function
exposure_pair_sums(B::Arr3Num, u::MatNum, t::Integer, k::Integer, l::Integer) -> ExposurePairSumsReturn the weighted sums of one pair of factor exposures over the assets they share at one observation.
An asset enters when both of its exposures are finite and its weight is finite and positive, so the support is the one the pair shares and not the one either factor holds alone. The correlation of the pair is a function of these six sums alone.
Arguments
B: Exposure historyassets × factors × observations, unlagged.u: Resolved weight historyobservations × assets.t: Position of the observation.k,l: Positions of the two factors.
Returns
m::ExposurePairSums: The count of the shared assets, the weight sum, the two weighted sums, the two weighted square sums and the weighted cross sum.
Related
PortfolioOptimisers.exposure_cross_section_std — Function
exposure_cross_section_std(B::Arr3Num, u::MatNum, t::Integer, k::Integer)Return the weighted cross-sectional standard deviation of one factor exposure at one observation.
The function normalises the weights over the assets at which the exposure is finite and the weight is finite and positive, so an absent exposure costs its own asset and no other. It clamps the weighted mean to the range of the cross-section, so a constant cross-section has a standard deviation of exactly 0. An observation at which the factor carries no weight has no answer.
Arguments
B: Exposure historyassets × factors × observations, unlagged.u: Resolved weight historyobservations × assets.t: Position of the observation.k: Position of the factor.
Returns
sigma::Real: The standard deviation, orNaN.
Related
PortfolioOptimisers.exposure_universe_size — Function
exposure_universe_size(u::MatNum, t::Integer)Return the number of assets in the universe of one observation.
The universe is the assets of finite positive weight, which is every asset when the caller reads no weight history.
Arguments
u: Resolved weight historyobservations × assets.t: Position of the observation.
Returns
n::Int: Number of assets in the universe.
Related
PortfolioOptimisers.exposure_covered_count — Function
exposure_covered_count(B::Arr3Num, u::MatNum, t::Integer, k::Integer)Return the number of assets of the universe of one observation at which one factor exposure is finite.
Arguments
B: Exposure historyassets × factors × observations, unlagged.u: Resolved weight historyobservations × assets.t: Position of the observation.k: Position of the factor.
Returns
n::Int: Number of covered assets.
Related
PortfolioOptimisers.exposure_coverage_weights — Function
exposure_coverage_weights(weighting::Option{<:AbstractOrthogonalityMetric},
csfm::CrossSectionalFactorModel)
exposure_coverage_weights(weighting::RegressionWeightMetric,
csfm::CrossSectionalFactorModel)Return the weight history that sets the universe of exposure_coverage.
The regression weights state the estimation universe of the fit. A block that carries none was fitted with a unit weight on every asset, so under RegressionWeightMetric the function returns csfm.rw as it stands, and nothing reads as the universe of every asset. Every other metric reads its history through cs_diagnostic_weights, which refuses an absent one by name.
Arguments
weighting: The metric that names the history.csfm: A cross-sectional factor model block.
Validation
- Under a metric other than
RegressionWeightMetric, the field that the metric names is notnothing, else anIsNothingErrorthat names the field.
Returns
u::Option{<:MatNum}:observations × assets, ornothingfor the universe of every asset.
Related
PortfolioOptimisers.cs_diagnostic_exposures — Function
cs_diagnostic_exposures(csfm::CrossSectionalFactorModel)
cs_diagnostic_exposures(Ms::Nothing)
cs_diagnostic_exposures(Ms::Arr3Num)Return the unlagged exposure history an exposure diagnostic reads off a factor model block.
The exposure group reads the history as the panel wrote it, so it takes no lag and no family re-basis. A method for nothing handles the absent case, so the function carries no branch, and its message names the field that the caller must populate.
Arguments
csfm: A cross-sectional factor model block.Ms: TheMsfield of the block, ornothing.
Validation
csfm.Msis notnothing. Otherwise the verb raises anIsNothingErrorthat namesMs.
Returns
Ms::Arr3Num: Exposure historyassets × factors × observations.
Related
PortfolioOptimisers.cs_masked_vif — Function
cs_masked_vif(B::Arr3Num, mask::AbstractMatrix{Bool}, u::MatNum)Return the variance inflation factors of a design whose mask a caller has already resolved.
Arguments
B: Exposure historyassets × factors × observations, already lagged.mask: Eligibility maskobservations × assets.u: Resolved weight historyobservations × assets, zero outside the mask.
Returns
vif::Matrix{<:Real}:observations × factors,NaNat an observation with no degrees of freedom.
Related
PortfolioOptimisers.cs_masked_condition_number — Function
cs_masked_condition_number(B::Arr3Num, mask::AbstractMatrix{Bool}, u::MatNum)Return the condition numbers of a design whose mask a caller has already resolved.
Arguments
B: Exposure historyassets × factors × observations, already lagged.mask: Eligibility maskobservations × assets.u: Resolved weight historyobservations × assets, zero outside the mask.
Returns
kappa::Vector{<:Real}: One entry per observation,NaNat an observation with no degrees of freedom.
Related