Cross-Sectional Idiosyncratic Diagnostics: private API

Types

PortfolioOptimisers.RowMoments — Type
struct RowMoments{__T_n, __T_m2, __T_m3, __T_m4}

Holds the count and the three central moments of one cross-section of standardised idiosyncratic returns.

This type is an implementation detail and is not intended for direct use. idio_row_moments makes it, and idio_calibration, idio_kurtosis and idio_skewness read it. The three moments are numbers of one type, so a record names them where a plain tuple would let a swap pass silently.

Fields

  • n: n: Number of assets at which the standardised return is finite.
  • m2: m2: Second central moment, or NaN when n is zero.
  • m3: m3: Third central moment, or NaN when n is zero.
  • m4: m4: Fourth central moment, or NaN when n is zero.

Related

source

Functions

PortfolioOptimisers.standardised_idio_value — Function
standardised_idio_value(e::Real, v::Real)

Return one standardised idiosyncratic return.

The verb divides the idiosyncratic return by the standard deviation the fit predicted for it. The answer is NaN where the division has no meaning. A variance that is not positive, a variance that is not finite, and a return that is not finite each give NaN. A negative variance counts as zero, so a variance estimate that undershot gives NaN and does not raise.

Mathematical definition

\[\begin{align} z_{ti} &= \begin{cases} \dfrac{\varepsilon_{ti}}{\hat{\sigma}_{ti}} & \text{if } \hat{\sigma}_{ti} > 0 \text{ and the ratio is finite}\,, \\ \mathrm{NaN} & \text{otherwise}\,. \end{cases} \end{align}\]

Where:

  • $z_{ti}$: Standardised idiosyncratic return of asset $i$ at observation $t$.
  • $\varepsilon_{ti}$: Idiosyncratic return of asset $i$ at observation $t$.
  • $\hat{\sigma}_{ti} = \sqrt{\max(v_{ti}, 0)}$: Predicted idiosyncratic volatility of asset $i$ at observation $t$. A negative variance counts as zero.
  • $v_{ti}$: Idiosyncratic variance of asset $i$ that the fit estimated from the observations up to $t$, so it is the forecast for observation $t + 1$.

Arguments

  • e: One idiosyncratic return.
  • v: The idiosyncratic variance predicted for it.

Returns

  • z::Real: The standardised return, or NaN.

Related

source
PortfolioOptimisers.idio_predicted_volatility — Function
idio_predicted_volatility(vs::MatNum)

Return the idiosyncratic volatility history the fit predicted.

A negative variance counts as zero, so a variance estimate that undershot gives 0 and does not raise. The two dependence series rank the assets by this quantity.

Mathematical definition

\[\begin{align} \hat{\sigma}_{ti} &= \sqrt{\max(v_{ti}, 0)}\,. \end{align}\]

Where:

  • $\hat{\sigma}_{ti} = \sqrt{\max(v_{ti}, 0)}$: Predicted idiosyncratic volatility of asset $i$ at observation $t$. A negative variance counts as zero.
  • $v_{ti}$: Idiosyncratic variance of asset $i$ that the fit estimated from the observations up to $t$, so it is the forecast for observation $t + 1$.

Arguments

  • vs: Idiosyncratic variance history observations × assets.

Returns

  • s::Matrix{<:Real}: Predicted volatility observations × assets, of a floating-point type. A variance that is not finite gives NaN.

Related

source
PortfolioOptimisers.idio_row_moments — Function
idio_row_moments(z::MatNum, t::Integer) -> RowMoments

Return the count and the three central moments of one cross-section of standardised idiosyncratic returns.

The calibration, the excess kurtosis and the skewness are each a function of these four numbers alone. So the verb makes its two passes over the cross-section once, and three series read the answer. An entry that is not finite enters neither the count nor a moment.

Mathematical definition

\[\begin{align} \bar{z}_{t} &= \frac{1}{n_{t}} \sum_{i \in \mathcal{F}_{t}} z_{ti}\,, \\ m_{pt} &= \frac{1}{n_{t}} \sum_{i \in \mathcal{F}_{t}} \left( z_{ti} - \bar{z}_{t} \right)^{p}\,, \quad p \in \{2, 3, 4\}\,. \end{align}\]

Where:

  • $\bar{z}_{t}$: Mean of the finite standardised returns of observation $t$.
  • $m_{pt}$: Central moment of order $p$ of the finite standardised returns of observation $t$.
  • $z_{ti}$: Standardised idiosyncratic return of asset $i$ at observation $t$.
  • $\mathcal{F}_{t}$: Finite cross-section of observation $t$, the assets whose standardised return $z_{ti}$ is finite.
  • $n_{t}$: Count of the assets in $\mathcal{F}_{t}$.

A cross-section whose finite entries are all equal has $m_{pt} = 0$ for every $p$.

Algorithm

  1. Pass over row t of z once. Over the finite entries, find the count n, the sum s, the least entry lo and the greatest entry hi.
  2. When n is zero, return NaN for the three moments.
  3. Divide s by n and clamp the answer to [lo, hi], giving the mean m. A mean of equal values can carry round-off, so without the clamp a constant cross-section would give a tiny positive m2 in place of zero. With the clamp, m equals the common value exactly, and every deviation is zero.
  4. Pass over row t again. Sum the second, third and fourth powers of the deviations from m, and divide each sum by n, giving m2, m3 and m4.

Arguments

  • z: Standardised idiosyncratic returns observations × assets.
  • t: Position of the observation.

Returns

  • m::RowMoments: The count n and the moments m2, m3 and m4, as RowMoments states them. n is an Int, and each moment is NaN when n is zero.

Related

source
PortfolioOptimisers.idio_vol_dependence — Function
idio_vol_dependence(eps::MatNum, vs::MatNum, standardise::Bool, ties::Symbol)

Return the rank correlation of the predicted idiosyncratic volatility against the next observation's absolute idiosyncratic return, standardised or not.

It does the work of idio_vol_ic and of idio_vol_residual_dependence. The two read the same two cross-sections, and differ only in whether they divide the target by the predicted volatility. Both score the volatility the fit predicted at observation $t$ against what the asset realised at observation $t + 1$, so the series has one entry fewer than the history. Those two docstrings state the mathematics.

Algorithm

  1. Check that eps is not empty, that vs has its size, and that it has more than one observation.
  2. Compute the predicted volatility sig with idio_predicted_volatility.
  3. For each observation t but the last, fill a with row t of sig. Fill b with the absolute idiosyncratic returns of observation t + 1. When standardise is true, divide each entry of b by the volatility predicted at observation t, through standardised_idio_value.
  4. Correlate a and b with cs_spearman_correlation under min_count = 5 and ties, giving entry t of c.

Arguments

  • eps: Idiosyncratic return history observations × assets.
  • vs: Idiosyncratic variance history observations × assets.
  • standardise: Divide the absolute return of observation $t + 1$ by the volatility predicted at observation $t$.
  • 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

  • !isempty(eps).
  • size(vs) == size(eps).
  • size(eps, 1) > 1.
  • The rules of cs_ranks.

Returns

  • c::Vector{<:Real}: The series, observations - 1 entries. Entry t reads observations t and t + 1. An observation that shares fewer than five finite assets is NaN.

Related

source
PortfolioOptimisers.idio_nan_mean — Function
idio_nan_mean(v::VecNum)

Return the mean of the finite entries of a series.

A diagnostic series is NaN at an observation that had too few assets, and the summary reads the observations that answered. This verb states that rule once for the four means the summary takes.

Mathematical definition

\[\begin{align} \bar{a} &= \frac{1}{|\mathcal{A}|} \sum_{t \in \mathcal{A}} a_{t}\,. \end{align}\]

Where:

  • $\bar{a}$: Mean of the finite entries.
  • $a_{t}$: Diagnostic series value at observation $t$.
  • $\mathcal{A}$: Finite observations of a diagnostic series, those at which $a_{t}$ is finite.

The mean is not defined for an empty $\mathcal{A}$.

Arguments

  • v: The series.

Returns

  • m::Real: The mean of the finite entries, or NaN when the series has none.

Related

source
PortfolioOptimisers.idio_nan_median — Function
idio_nan_median(v::VecNum)

Return the median of the finite entries of a series.

The summary reads the median of the calibration series beside its mean. One observation with a cross-section that is almost constant moves the mean, but not the median.

Mathematical definition

\[\begin{align} \tilde{a} &= \operatorname{median} \left\{ a_{t} : t \in \mathcal{A} \right\}\,. \end{align}\]

Where:

  • $\tilde{a}$: Median of the finite entries. For an even count it is the mean of the two middle entries.
  • $a_{t}$: Diagnostic series value at observation $t$.
  • $\mathcal{A}$: Finite observations of a diagnostic series, those at which $a_{t}$ is finite.

The median is not defined for an empty $\mathcal{A}$.

Arguments

  • v: The series.

Returns

  • m::Real: The median of the finite entries, or NaN when the series has none.

Related

source
PortfolioOptimisers.idio_diagnostic_data — Function
idio_diagnostic_data(csfm::CrossSectionalFactorModel)
idio_diagnostic_data(csr::Nothing, vs::Option{<:MatNum})
idio_diagnostic_data(csr::CrossSectionalRegression, vs::Nothing)
idio_diagnostic_data(csr::CrossSectionalRegression, vs::MatNum)

Return the idiosyncratic return history and the idiosyncratic variance history that an idiosyncratic diagnostic reads off a factor model block.

The group reads the residual of the fit against the variance the fit predicted for it. Neither history has a factor axis, so the group takes no lag and no family re-basis, and it reads the two histories as the block wrote them. Dispatch, not a branch, selects the absent case, and its message names the field the caller must populate.

A pair that the h1 field of the regression marks has a leverage of one: the design fitted its return exactly, so its residual is zero by construction and its variance under the design is zero too. Its standardised return is $0 / 0$, which is not defined, so the verb writes NaN over its residual and every verb of the group leaves the pair out. The verb writes NaN over its variance too, as forecast_idiosyncratic_variances does, because a variance that read such residuals is not a forecast of the next return: under ahead = true the first unmarked row after a marked row would divide by it, and idio_vol_ic would rank it. A variance that read only such residuals and that the mask does not reach is zero, and standardised_idio_value answers NaN for it.

Arguments

  • csfm: A cross-sectional factor model block.
  • csr: The csr field of the block, or nothing.
  • vs: The vs field of the block, or nothing.

Validation

  • csfm.csr is not nothing, else the verb raises an IsNothingError that names csr.
  • csfm.vs is not nothing, else the verb raises an IsNothingError that names vs.

Returns

  • eps::MatNum: Idiosyncratic return history observations × assets, NaN at a pair that h1 marks.
  • vs::MatNum: Idiosyncratic variance history observations × assets, NaN at a pair that h1 marks.

Related

source