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

source

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 history assets × factors × observations, unlagged.
  • w: Cross-sectional weight history observations × assets, or nothing for equal weights.

Validation

  • !isempty(B).
  • size(w) == (size(B, 3), size(B, 1)), when w is present.
  • No finite entry of w is negative.

Returns

  • u::MatNum: Weight history observations × assets. It is a history of ones when w is nothing, and w itself otherwise.

Related

source
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

  1. Count the assets that enter into n. Accumulate the weight sum ws, the two weighted sums sa and sb, and the least and greatest value of each cross-section, lo and hi, over them.
  2. Answer NaN when fewer than min_count assets enter, or when the weight sum is zero.
  3. Clamp each weighted mean, ma and mb, 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.
  4. Accumulate the weighted central moments cab, caa and cbb over the same assets.
  5. Answer NaN when the denominator den is at or under eps. 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 is NaN.

Returns

  • rho::Real: The correlation, or NaN.

Examples

julia> PortfolioOptimisers.cs_weighted_correlation([1.0, 2.0, 3.0], [2.0, 4.0, 6.0], ones(3))1.0

Related

source
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: true when the asset enters.

Related

source
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

  1. Sort the positions of key with a stable sort, giving p.
  2. Walk p in runs. Under :average, a run holds every entry of one key. Under :ordinal, a run holds one entry.
  3. Write the mean position of the run to each entry of the run that is in the mask. Leave NaN at each entry outside it.

Arguments

  • key: Sort key of each asset. The key of a masked asset must be Inf, so the mask sorts to the end.
  • valid: Mask, one entry per asset. A false entry gets NaN.
  • ties: Rule that ranks the equal values of a cross-section. :average gives 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. :ordinal gives 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

Returns

  • r::VecNum: Rank of each asset, or NaN outside 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.0

Related

source
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. Under ties = :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 ties names.
  • $\boldsymbol{1}$: Equal weights.

Algorithm

  1. Mark the assets at which both values are finite.
  2. Rank each cross-section over those assets with cs_ranks.
  3. Correlate the two rank vectors with cs_weighted_correlation under 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 is NaN.
  • ties: Rule that ranks the equal values of a cross-section. :average gives 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. :ordinal gives 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

Returns

  • rho::Real: The rank correlation, or NaN.

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

Related

source
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 history assets × factors × observations, unlagged.
  • u: Resolved weight history observations × assets.
  • k, l: Positions of the two factors.

Returns

  • rho::Real: The time-averaged correlation, 0 by convention, or NaN.

Related

source
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 history assets × factors × observations, unlagged.
  • u: Resolved weight history observations × assets.
  • t: Position of the observation.
  • k, l: Positions of the two factors.

Returns

  • rho::Real: The correlation, or NaN.
  • degenerate::Bool: true when the pair shares three assets and one of the two cross-sections is constant over them.

Related

source
PortfolioOptimisers.exposure_pair_sums — Function
exposure_pair_sums(B::Arr3Num, u::MatNum, t::Integer, k::Integer, l::Integer) -> ExposurePairSums

Return 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 history assets × factors × observations, unlagged.
  • u: Resolved weight history observations × 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

source
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 history assets × factors × observations, unlagged.
  • u: Resolved weight history observations × assets.
  • t: Position of the observation.
  • k: Position of the factor.

Returns

  • sigma::Real: The standard deviation, or NaN.

Related

source
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 history observations × assets.
  • t: Position of the observation.

Returns

  • n::Int: Number of assets in the universe.

Related

source
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 not nothing, else an IsNothingError that names the field.

Returns

  • u::Option{<:MatNum}: observations × assets, or nothing for the universe of every asset.

Related

source
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: The Ms field of the block, or nothing.

Validation

  • csfm.Ms is not nothing. Otherwise the verb raises an IsNothingError that names Ms.

Returns

  • Ms::Arr3Num: Exposure history assets × factors × observations.

Related

source
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 history assets × factors × observations, already lagged.
  • mask: Eligibility mask observations × assets.
  • u: Resolved weight history observations × assets, zero outside the mask.

Returns

  • vif::Matrix{<:Real}: observations × factors, NaN at an observation with no degrees of freedom.

Related

source
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 history assets × factors × observations, already lagged.
  • mask: Eligibility mask observations × assets.
  • u: Resolved weight history observations × assets, zero outside the mask.

Returns

  • kappa::Vector{<:Real}: One entry per observation, NaN at an observation with no degrees of freedom.

Related

source